您正在查看 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 载荷的形式返回所需的确切数据。
如果修改文档会发生什么情况？
每个 OpenAPI 或 GraphQL 文档都用作整个 API 生命周期内的可靠来源。在 API 生命周期（从开发、发布到监控）的每个阶段都会用到这份文档。
当您修改或删除某个文档时，它会影响以下行：
- 如果您修改文档，则需要手动修改相关工件（包括 API 代理和公开其资源的任何 API 产品），然后重新生成 API 参考文档，以反映在该文档中实现的更改。
- 如果您删除文档，则需要手动删除相关工件（包括 API 代理）并修改所有 API 产品以删除相关资源，然后重新生成 API 参考文档，以反映移除的文档及其资源。
根据 OpenAPI 文档创建 API 代理会发生什么情况？
在 Edge 中，您可以根据 OpenAPI 文档创建 API 代理。您只需点击几下，便可自动生成包含路径、参数、条件流和目标端点的 API 代理。然后，您可以添加 OAuth 安全机制、速率限制和缓存等功能。
您可以通过 OpenAPI 文档创建 API 代理，如以下部分所述：
- 从规范列表中获取，如根据规范列表中的规范创建 API 代理中所述。注意：传统版 Edge 中不提供规格列表。
- 按照使用 OpenAPI 规范生成代理中所述，通过 API 代理管理器，调用“构建代理向导”并选择从 OpenAPI 文档创建 API 代理。
发布 API 时，您需要截取 OpenAPI 文档的快照，以生成 API 参考文档。该快照表示规范存储区中说明文档的特定修订版本。