导入 API 文档
与导入 API 实体定义一样，您可以在 API Gateway 中将文档部分从外部 OpenAPI 文件导入到 API 中。您需要在有效的 OpenAPI 定义文件中指定 x-amazon-apigateway-documentation 对象 扩展中待导入的文档部分。导入文档的过程不会更改现有的 API 实体定义。
您可以选择在 API Gateway 中将新指定的文档部分合并到现有的文档部分中，也可以覆盖现有的文档部分。在 MERGE 模式下，在 OpenAPI 文件中定义的新文档部分会添加到 API 的 DocumentationParts 集合中。如果存在已导入的 DocumentationPart，在两者属性不同的情况下，导入的属性将替代现有属性。其他现有的文档属性不受影响。在 OVERWRITE 模式中，整个 DocumentationParts 集合将被替代，具体取决于导入的 OpenAPI 定义文件。
使用 API Gateway REST API 导入文档部分
要使用 API Gateway REST API 导入 API 文档，请调用 documentationpart:import 操作。以下示例显示了如何使用单个 GET / 方法覆盖 API 的现有文档部分，并在成功后返回 200 OK 响应。
- OpenAPI 3.0
-
PUT /restapis/<restapi_id>/documentation/parts&mode=overwrite&failonwarnings=true
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
{
"openapi": "3.0.0",
"info": {
"description": "description",
"version": "1",
"title": "doc"
},
"paths": {
"/": {
"get": {
"description": "Method description.",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
}
}
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.3",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"info": {
"description": "API info description 4",
"version": "API info version 3"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description."
}
},
{
"location": {
"type": "MODEL",
"name": "Empty"
},
"properties": {
"title": "Empty Schema"
}
},
{
"location": {
"type": "RESPONSE",
"method": "GET",
"statusCode": "200"
},
"properties": {
"description": "200 response"
}
}
]
},
"servers": [
{
"url": "/"
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
- OpenAPI 2.0
-
PUT /restapis/<restapi_id>/documentation/parts&mode=overwrite&failonwarnings=true
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
{
"swagger": "2.0",
"info": {
"description": "description",
"version": "1",
"title": "doc"
},
"host": "",
"basePath": "/",
"schemes": [
"https"
],
"paths": {
"/": {
"get": {
"description": "Method description.",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
}
}
}
},
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.3",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"info": {
"description": "API info description 4",
"version": "API info version 3"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description."
}
},
{
"location": {
"type": "MODEL",
"name": "Empty"
},
"properties": {
"title": "Empty Schema"
}
},
{
"location": {
"type": "RESPONSE",
"method": "GET",
"statusCode": "200"
},
"properties": {
"description": "200 response"
}
}
]
}
}
如果成功，此请求将返回一个 200 OK 响应，并在其负载中包含导入的 DocumentationPartId。
{
"ids": [
"kg3mth",
"796rtf",
"zhek4p",
"5ukm9s"
]
}
另外，您也可以调用 restapi:import 或 restapi:put，并在 x-amazon-apigateway-documentation 对象中提供文档部分，作为 API 定义的输入 OpenAPI 文件的一部分。要从 API 导入中排除文档部分，请在请求查询参数中设置 ignore=documentation。
使用 API Gateway 控制台导入文档部分
以下说明介绍了如何导入文档部分。
