API 设计概览

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档。 信息

在设计阶段，您可以定义 API 的要求。作为 API 设计者，您可以规划您希望向用户呈现的服务，并设计 API 来访问这些服务。您可以创建以下文档之一来捕获您的 API 要求：

  • OpenAPI 文档
  • GraphQL 架构

以下部分详细介绍了 OpenAPI 和 GraphQL 文档以及它们在 API 生命周期中的作用。 如需了解这两种 API 设计选项的比较，请参阅这篇博文中的 REST 和 GraphQL 比较。

什么是 OpenAPI 规范？


“OpenAPI 计划 (OAI) 专注于根据 Swagger 规范创建、改进和推广供应商中立的 API 描述格式。”如需详细了解 OpenAPI 计划，请访问 https://openapis.org。

OpenAPI 文档使用标准格式来描述 RESTful API。OpenAPI 文档采用 JSON 或 YAML 机器可读格式编写，但也便于人类阅读和理解。OpenAPI 规范提供 API 元素的正式描述，例如基本路径、路径和动词、标头、查询参数、内容类型、响应模型等。此外，OpenAPI 文档通常用于生成 API 文档。

以下是摘自描述 Apigee 简单 Hello World 示例的 OpenAPI 文档中的一个代码片段。如需了解详情，请查看 GitHub 上的 OpenAPI 规范。

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

有很多关于 OpenAPI 规范的可靠信息来源。您不妨从 OpenAPI 计划网站入手，您可以在这里找到与 OpenAPI 规范相关的概览、博客和链接。有关架构元素和数据类型的详细说明，请参阅相关规范。

您可以从 OpenAPI 规范代码库下载许多 JSON 和 YAML 格式的示例 OpenAPI 文档。

什么是 GraphQL 架构？

GraphQL 架构描述了 API 中可供客户端查询的数据。

使用 GraphQL 有如下好处：

  • 通过单个端点便可提供对给定操作的所有字段的访问权限
  • 提供了一种强大的查询语言（称为“架构定义语言”），可让您精确访问所需的数据，防止数据过度提取或提取不足
  • 并行处理查询

如需详细了解 GraphQL，请参阅 graphql.org。

下面提供了一个 GraphQL 架构示例，用于定义数据入口点（查询类型）、可用写入操作（更改类型）和数据类型。

type Query {
  Greeting: String
  students: [Student]
}
type Mutation {
  createStudent(firstName: String!, lastName: String!): Student!
}
type Subscription {
  newStudent: Student!
}
type Student {
  Id: ID!
  firstName: String!
  lastName: String!
  password: String!
  collegeId: String!
}

您可以查询 GraphQL 架构，并以 JSON 载荷的形式返回所需的确切数据。

GraphQL 查询和结果

如果修改文档会发生什么情况？

每个 OpenAPI 或 GraphQL 文档都用作整个 API 生命周期内的可靠来源。这份文档在 API 生命周期的每个阶段（从开发到发布再到监控）使用。

当您修改或删除某个文档时，它会影响以下行：

  • 如果您修改文档，则需要手动修改相关工件（包括 API 代理和公开其资源的任何 API 产品），然后重新生成 API 参考文档，以反映在该文档中实现的更改。
  • 如果您删除文档，则需要手动删除相关工件（包括 API 代理）并修改所有 API 产品以删除相关资源，然后重新生成 API 参考文档，以反映移除的文档及其资源。

根据 OpenAPI 文档创建 API 代理会发生什么情况？

在 Edge 中，您可以从 OpenAPI 文档创建 API 代理。您只需点击几下，便可自动生成包含路径、参数、条件流和目标端点的 API 代理。然后，您可以添加 OAuth 安全机制、速率限制和缓存等功能。

您可以从 OpenAPI 文档创建 API 代理，如以下部分所述：

发布 API 时，您需要截取 OpenAPI 文档的快照，以生成 API 参考文档。该快照表示规范存储区中说明文档的特定修订版本。