本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 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` 實體都已新增一個文件組件。呼叫上述文件匯出命令，我們會取得下列輸出，其中 `x-amazon-apigateway-documentation` 物件內所列的文件組件是標準 OpenAPI 檔案的延伸。
------
#### [ 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) 中的說明進行。