# 使用 API Gateway REST API 发布 API 文档
要发布 API 文档，请创建、更新或获取文档快照，然后将该文档快照与一个 API 阶段关联。创建文档快照时，您也可以同时将其与一个 API 阶段关联。
**Topics**
+ [创建文档快照并将其与一个 API 阶段关联](#api-gateway-documenting-api-publishing-create-documentation-version-with-stage)
+ [创建文档快照](#api-gateway-documenting-api-publishing-create-documentation-version)
+ [更新文档快照](#api-gateway-documenting-api-publishing-update-documentation-version)
+ [获取文档快照](#api-gateway-documenting-api-publishing-get-documentation-version)
+ [将文档快照与一个 API 阶段关联](#api-gateway-documenting-api-publishing-stage-association)
+ [下载与阶段关联的文档快照](#api-gateway-documenting-api-publishing-export-documentation-version)
## 创建文档快照并将其与一个 API 阶段关联
要创建 API 文档部分的快照，并同时将其与一个 API 阶段关联，请提交以下 `POST` 请求：
```
POST /restapis/restapi_id/documentation/versions HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"documentationVersion" : "1.0.0",
"stageName": "prod",
"description" : "My API Documentation v1.0.0"
}
```
如果成功，操作将返回 `200 OK` 响应，其中包含新创建的 `DocumentationVersion` 实例作为有效载荷。
或者，您可以先创建一个文档快照，但不将其与一个 API 阶段关联，然后调用 [restapi:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html)，以便将该快照与指定的 API 阶段关联。您也可以更新或查询现有的文档快照，然后更新其阶段关联。我们将在接下来的四个部分中展示相关步骤。
## 创建文档快照
要创建 API 文档部分的快照，请创建新的 [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) 资源，并将其添加到 API 的 [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) 集合中：
```
POST /restapis/restapi_id/documentation/versions HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"documentationVersion" : "1.0.0",
"description" : "My API Documentation v1.0.0"
}
```
如果成功，操作将返回 `200 OK` 响应，其中包含新创建的 `DocumentationVersion` 实例作为有效载荷。
## 更新文档快照
您只需修改对应的 [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) 资源的 `description` 属性，即可更新文档快照。以下示例展示了如何更新由版本标识符 `version` (例如 `1.0.0`) 进行标识的文档快照的描述。
```
PATCH /restapis/restapi_id/documentation/versions/version HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"patchOperations": [{
"op": "replace",
"path": "/description",
"value": "My API for testing purposes."
}]
}
```
如果成功，操作将返回 `200 OK` 响应，其中包含更新后的 `DocumentationVersion` 实例作为有效载荷。
## 获取文档快照
要获取文档快照，请提交针对指定 [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) 资源的 `GET` 请求。以下示例展示了如何获取给定版本标识符 (1.0.0) 的文档快照。
```
GET /restapis//documentation/versions/1.0.0 HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
## 将文档快照与一个 API 阶段关联
要发布 API 文档，请将文档快照与一个 API 阶段关联。您必须创建 API 阶段，然后才能将文档版本与该阶段关联。
要使用 [API Gateway REST API](https://docs.aws.amazon.com/apigateway/latest/api/) 将文档快照与一个 API 阶段关联，请调用 [stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) 操作，以在 `stage.documentationVersion` 属性上设置所需的文档版本：
```
PATCH /restapis/RESTAPI_ID/stages/STAGE_NAME
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"patchOperations": [{
"op": "replace",
"path": "/documentationVersion",
"value": "VERSION_IDENTIFIER"
}]
}
```
## 下载与阶段关联的文档快照
在某一版本的文档部分与某个阶段相关联后，您可以使用 API Gateway 控制台、API Gateway REST API、某种开发工具包或适用于 API Gateway 的 AWS CLI，将文档部分与 API 实体定义导出到外部文件。该过程与导出 API 的过程一样。导出的文件格式可以是 JSON 或 YAML。
使用 API Gateway REST API，还可以明确设置 `extension=documentation,integrations,authorizers` 查询参数，以将 API 文档部分、API 集成和授权方包含在 API 导出中。默认情况下，在导出 API 时会包含文档部分，但不包括集成和授权方。API 导出的默认输出适用于文档的分发。
要使用 API Gateway REST API 将 API 文档导出到外部 JSON OpenAPI 文件中，请提交以下 `GET` 请求：
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=documentation HTTP/1.1
Accept: application/json
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
在这里，`x-amazon-apigateway-documentation` 对象包含文档部分，而 API 实体定义包含 OpenAPI 支持的文档属性。输出并不包含集成或 Lambda 授权方（以前称为自定义授权方）的详细信息。要包含这两项详细信息，请设置 `extensions=integrations,authorizers,documentation`。要包含集成的详细信息，但不包含授权方的详细信息，请设置 `extensions=integrations,documentation`。
您必须在请求中设置 `Accept:application/json` 标头，才能以 JSON 文件格式输出结果。要生成 YAML 输出，请将请求标头更改为 `Accept:application/yaml`。
例如，我们来查看一个在根资源 (`GET`) 上显示简单 `/` 方法的 API。此 API 拥有四个在 OpenAPI 定义文件中定义的 API 实体，其类型分别为 `API`、`MODEL`、`METHOD` 和 `RESPONSE`。每个 `API`、`METHOD` 和 `RESPONSE` 实体都已添加文档部分。通过调用前面的 documentation-exporting 命令，我们将获得以下输出，而文档部分将作为标准 OpenAPI 文件的扩展列在 `x-amazon-apigateway-documentation` 对象中。
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"description": "API info description",
"version": "2016-11-22T22:39:14Z",
"title": "doc",
"x-bar": "API info x-bar"
},
"paths": {
"/": {
"get": {
"description": "Method description.",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-example": "x- Method example"
},
"x-bar": "resource x-bar"
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.0",
"createdDate": "2016-11-22T22:41:40Z",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"foo": "API foo",
"x-bar": "API x-bar",
"info": {
"description": "API info description",
"version": "API info version",
"foo": "API info foo",
"x-bar": "API info x-bar"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description.",
"x-example": "x- Method example",
"foo": "Method foo",
"info": {
"version": "method info version",
"description": "method info description",
"foo": "method info foo"
}
}
},
{
"location": {
"type": "RESOURCE"
},
"properties": {
"description": "resource description",
"foo": "resource foo",
"x-bar": "resource x-bar",
"info": {
"description": "resource info description",
"version": "resource info version",
"foo": "resource info foo",
"x-bar": "resource info x-bar"
}
}
}
]
},
"x-bar": "API x-bar",
"servers": [
{
"url": "https://rznaap68yi.execute-api.ap-southeast-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/test"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"description" : "API info description",
"version" : "2016-11-22T22:39:14Z",
"title" : "doc",
"x-bar" : "API info x-bar"
},
"host" : "rznaap68yi.execute-api.ap-southeast-1.amazonaws.com",
"basePath" : "/test",
"schemes" : [ "https" ],
"paths" : {
"/" : {
"get" : {
"description" : "Method description.",
"produces" : [ "application/json" ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/Empty"
}
}
},
"x-example" : "x- Method example"
},
"x-bar" : "resource x-bar"
}
},
"definitions" : {
"Empty" : {
"type" : "object",
"title" : "Empty Schema"
}
},
"x-amazon-apigateway-documentation" : {
"version" : "1.0.0",
"createdDate" : "2016-11-22T22:41:40Z",
"documentationParts" : [ {
"location" : {
"type" : "API"
},
"properties" : {
"description" : "API description",
"foo" : "API foo",
"x-bar" : "API x-bar",
"info" : {
"description" : "API info description",
"version" : "API info version",
"foo" : "API info foo",
"x-bar" : "API info x-bar"
}
}
}, {
"location" : {
"type" : "METHOD",
"method" : "GET"
},
"properties" : {
"description" : "Method description.",
"x-example" : "x- Method example",
"foo" : "Method foo",
"info" : {
"version" : "method info version",
"description" : "method info description",
"foo" : "method info foo"
}
}
}, {
"location" : {
"type" : "RESOURCE"
},
"properties" : {
"description" : "resource description",
"foo" : "resource foo",
"x-bar" : "resource x-bar",
"info" : {
"description" : "resource info description",
"version" : "resource info version",
"foo" : "resource info foo",
"x-bar" : "resource info x-bar"
}
}
} ]
},
"x-bar" : "API x-bar"
}
```
------
对于在文档部分的 `properties` 映射中定义且符合 OpenAPI 规范的属性，API Gateway 会将该属性插入关联的 API 实体定义中。`x-something` 的一个属性是标准 OpenAPI 扩展。此扩展将传播到 API 实体定义中。例如，请查看 `x-example` 方法的 `GET` 属性。类似 `foo` 的属性不属于 OpenAPI 规范，也不会插入到关联的 API 实体定义中。
如果某个文档呈现工具（例如 [OpenAPI UI](https://swagger.io/tools/swagger-ui/)）通过解析 API 实体定义来提取文档属性，则该工具将无法使用 `properties` 实例所有不符合 OpenAPI 规范的 `DocumentationPart` 属性。但是，如果某个文档呈现工具通过解析 `x-amazon-apigateway-documentation` 对象来获取内容，或者通过调用 [restapi:documentation-parts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 和 [documenationpart:by-id](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationPart.html) 从 API Gateway 中检索文档部分，则该工具可以展示所有文档属性。
要将具备 API 实体定义（包含集成详细信息）的文档导出为 JSON OpenAPI 文件，请提交以下 `GET` 请求：
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,documentation HTTP/1.1
Accept: application/json
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
要将具备 API 实体定义（包含集成和授权方的详细信息）的文档导出为 YAML OpenAPI 文件，请提交以下 `GET` 请求：
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,authorizers,documentation HTTP/1.1
Accept: application/yaml
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
要使用 API Gateway 控制台导出和下载 API 的已发布文档，请按照[使用 API Gateway 控制台导出 REST API](api-gateway-export-api.md#api-gateway-export-api-from-console) 中的说明操作。