本页面适用于 Apigee 和 Apigee Hybrid。
查看 Apigee Edge 文档。
在设计阶段，您可以定义 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 代理会发生什么情况？
您可以根据 OpenAPI 文档创建 API 代理。您只需点击几下，便可自动生成包含路径、参数、条件流和目标端点的 API 代理。然后，您可以添加 OAuth 安全机制、速率限制和缓存等功能。
您可以按照使用 OpenAPI 规范生成代理中的说明，使用“创建代理”向导根据 OpenAPI 文档创建 API 代理。如需获得实操经验，请完成根据 OpenAPI 规范创建 API 代理教程。
发布 API 时，您需要截取 OpenAPI 文档的快照，以生成 API 参考文档。该快照表示说明文档的特定修订版本。