使用 API Gateway REST API 发布 API 文档 - Amazon API Gateway
创建文档快照并将其与一个 API 阶段关联创建文档快照更新文档快照获取文档快照将文档快照与一个 API 阶段关联下载与阶段关联的文档快照
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用 API Gateway REST API 发布 API 文档

要发布 API 文档，请创建、更新或获取文档快照，然后将该文档快照与一个 API 阶段关联。创建文档快照时，您也可以同时将其与一个 API 阶段关联。

创建文档快照并将其与一个 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，以便将该快照与指定的 API 阶段关联。您也可以更新或查询现有的文档快照，然后更新其阶段关联。我们将在接下来的四个部分中展示相关步骤。

创建文档快照

要创建 API 文档部分的快照，请创建新的 DocumentationVersion 资源，并将其添加到 API 的 DocumentationVersions 集合中：

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 资源的 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 资源的 GET 请求。以下示例展示了如何获取给定版本标识符 (1.0.0) 的文档快照。

GET /restapis/<restapi_id>/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 将文档快照与一个 API 阶段关联，请调用 stage:update 操作，以在 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 的 Amazon 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）通过解析 API 实体定义来提取文档属性，则该工具将无法使用 properties 实例所有不符合 OpenAPI 规范的 DocumentationPart 属性。但是，如果某个文档呈现工具通过解析 x-amazon-apigateway-documentation 对象来获取内容，或者通过调用 restapi:documentation-parts 和 documenationpart:by-id 从 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 中的说明操作。