# 使用 API Gateway 控制台记录 API
<a name="api-gateway-documenting-api-quick-start-with-console"></a>

在本节中，我们将介绍如何使用 API Gateway 控制台创建和维护 API 的文档部分。

创建和编辑 API 文档的一个先决条件是您必须已创建 API。在本节中，我们使用 [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets) API 作为示例。要使用 API Gateway 控制台创建 API，请按照 [教程：通过导入示例创建 REST API](api-gateway-create-api-from-example.md)中的说明操作。

**Topics**
+ [记录 `API` 实体](#api-gateway-document-api-add-document-part-for-api-entity-with-console)
+ [记录 `RESOURCE` 实体](#api-gateway-document-api-add-document-part-for-resource-entity-with-console)
+ [记录 `METHOD` 实体](#api-gateway-document-api-add-document-part-for-method-entity-with-console)
+ [记录 `QUERY_PARAMETER` 实体](#api-gateway-document-api-add-document-part-for-request-query-entity-with-console)
+ [记录 `PATH_PARAMETER` 实体](#api-gateway-document-api-add-document-part-for-path-parameter-entity-with-console)
+ [记录 `REQUEST_HEADER` 实体](#api-gateway-document-api-add-document-part-for-request-header-entity-with-console)
+ [记录 `REQUEST_BODY` 实体](#api-gateway-document-api-add-document-part-for-request-body-entity-with-console)
+ [记录 `RESPONSE` 实体](#api-gateway-document-api-add-document-part-for-response-with-console)
+ [记录 `RESPONSE_HEADER` 实体](#api-gateway-document-api-add-document-part-for-response-header-entity-with-console)
+ [记录 `RESPONSE_BODY` 实体](#api-gateway-document-api-add-document-part-for-response-body-entity-with-console)
+ [记录 `MODEL` 实体](#api-gateway-document-api-add-document-part-for-model-entity-with-console)
+ [记录 `AUTHORIZER` 实体](#api-gateway-document-api-add-document-part-for-authorizer-entity-with-console)

## 记录 `API` 实体
<a name="api-gateway-document-api-add-document-part-for-api-entity-with-console"></a>

要为 `API` 实体添加新的文档部分，请执行以下操作：

1. 在主导航窗格中，选择**文档**，然后选择**创建文档部分**。

1. 对于**文档类型**，请选择 **API**。

   如果尚未为 `API` 创建文档部分，您将看到文档部分的 `properties` 映射编辑器。在文本编辑器中输入以下 `properties` 映射。

   ```
   {
     "info": {
       "description": "Your first API Gateway API.",
       "contact": {
           "name": "John Doe",
           "email": "john.doe@api.com"
       }
     }
   }
   ```
**注意**  
 您无需将 `properties` 映射编码成 JSON 字符串。API Gateway 控制台会对 JSON 对象进行字符串化。

1. 选择**创建文档部分**。

要在**资源**窗格中为 `API` 实体添加新的文档部分，请执行以下操作：

1. 在主导航窗格中，选择**资源**。

1. 选择 **API 操作**菜单，然后选择**更新 API 文档**。

      
![\[在 API Gateway 控制台中为 API 实体编辑文档\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/document-api-entity-using-new-console.png)

要编辑现有文档部分，请执行以下操作：

1. 在**文档**窗格中，选择**资源和方法**选项卡。

1. 选择 API 的名称，然后在 API 卡片上选择**编辑**。

## 记录 `RESOURCE` 实体
<a name="api-gateway-document-api-add-document-part-for-resource-entity-with-console"></a>

 要为 `RESOURCE` 实体添加新的文档部分，请执行以下操作：

1. 在主导航窗格中，选择**文档**，然后选择**创建文档部分**。

1. 对于**文档类型**，选择**资源**。

1. 对于**路径**，输入路径。

1. 在文本编辑器中输入描述，例如：

   ```
   {
       "description": "The PetStore's root resource."
   }
   ```

1. 选择**创建文档部分**。您可以为未列出的资源创建文档。

1.  如果需要，请重复上述步骤，以添加或编辑另一个文档部分。

要在**资源**窗格中为 `RESOURCE` 实体添加新的文档部分，请执行以下操作：

1. 在主导航窗格中，选择**资源**。

1. 选择资源，然后选择**更新文档**。

      
![\[在 API Gateway 控制台中为资源实体编辑文档\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/document-resource-entity-using-new-console.png)

要编辑现有文档部分，请执行以下操作：

1. 在**文档**窗格中，选择**资源和方法**选项卡。

1. 选择包含文档部分的资源，然后选择**编辑**。

## 记录 `METHOD` 实体
<a name="api-gateway-document-api-add-document-part-for-method-entity-with-console"></a>

 要为 `METHOD` 实体添加新的文档部分，请执行以下操作：

1. 在主导航窗格中，选择**文档**，然后选择**创建文档部分**。

1. 对于**文档类型**，选择**方法**。

1. 对于**路径**，输入路径。

1. 对于**方法**，选择 HTTP 动词。

1. 在文本编辑器中输入描述，例如：

   ```
   {
     "tags" : [ "pets" ],
     "summary" : "List all pets"
   }
   ```

1. 选择**创建文档部分**。您可以为未列出的方法创建文档。

1.  如果需要，请重复上述步骤，以添加或编辑另一个文档部分。

要在**资源**窗格中为 `METHOD` 实体添加新的文档部分，请执行以下操作：

1. 在主导航窗格中，选择**资源**。

1. 选择方法，然后选择**更新文档**。

      
![\[在 API Gateway 控制台中为方法实体编辑文档\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/document-method-entity-using-new-console.png)

要编辑现有文档部分，请执行以下操作：

1. 在**文档**窗格中，选择**资源和方法**选项卡。

1. 您可以选择方法或选择包含该方法的资源，然后使用搜索栏查找并选择您的文档部分。

1.  选择**编辑**。

## 记录 `QUERY_PARAMETER` 实体
<a name="api-gateway-document-api-add-document-part-for-request-query-entity-with-console"></a>

 要为 `QUERY_PARAMETER` 实体添加新的文档部分，请执行以下操作：

1. 在主导航窗格中，选择**文档**，然后选择**创建文档部分**。

1. 对于**文档类型**，选择**查询参数**。

1. 对于**路径**，输入路径。

1. 对于**方法**，选择 HTTP 动词。

1. 对于**名称**，输入名称。

1. 在文本编辑器中输入描述。

1. 选择**创建文档部分**。您可以为未列出的查询参数创建文档。

1.  如果需要，请重复上述步骤，以添加或编辑另一个文档部分。

要编辑现有文档部分，请执行以下操作：

1. 在**文档**窗格中，选择**资源和方法**选项卡。

1. 您可以选择查询参数或选择包含查询参数的资源，然后使用搜索栏查找和选择您的文档部分。

1. 选择**编辑**。

## 记录 `PATH_PARAMETER` 实体
<a name="api-gateway-document-api-add-document-part-for-path-parameter-entity-with-console"></a>

 要为 `PATH_PARAMETER` 实体添加新的文档部分，请执行以下操作：

1. 在主导航窗格中，选择**文档**，然后选择**创建文档部分**。

1. 对于**文档类型**，选择**路径参数**。

1. 对于**路径**，输入路径。

1. 对于**方法**，选择 HTTP 动词。

1. 对于**名称**，输入名称。

1. 在文本编辑器中输入描述。

1. 选择**创建文档部分**。您可以为未列出的路径参数创建文档。

1.  如果需要，请重复上述步骤，以添加或编辑另一个文档部分。

要编辑现有文档部分，请执行以下操作：

1. 在**文档**窗格中，选择**资源和方法**选项卡。

1. 您可以选择路径参数或选择包含路径参数的资源，然后使用搜索栏查找并选择您的文档部分。

1. 选择**编辑**。

## 记录 `REQUEST_HEADER` 实体
<a name="api-gateway-document-api-add-document-part-for-request-header-entity-with-console"></a>

 要为 `REQUEST_HEADER` 实体添加新的文档部分，请执行以下操作：

1. 在主导航窗格中，选择**文档**，然后选择**创建文档部分**。

1. 对于**文档类型**，选择**请求标头**。

1. 对于**路径**，输入请求标头的路径。

1. 对于**方法**，选择 HTTP 动词。

1. 对于**名称**，输入名称。

1. 在文本编辑器中输入描述。

1. 选择**创建文档部分**。您可以为未列出的请求标头创建文档。

1.  如果需要，请重复上述步骤，以添加或编辑另一个文档部分。

要编辑现有文档部分，请执行以下操作：

1. 在**文档**窗格中，选择**资源和方法**选项卡。

1. 您可以选择请求标头或选择包含请求标头的资源，然后使用搜索栏查找并选择您的文档部分。

1. 选择**编辑**。

## 记录 `REQUEST_BODY` 实体
<a name="api-gateway-document-api-add-document-part-for-request-body-entity-with-console"></a>

 要为 `REQUEST_BODY` 实体添加新的文档部分，请执行以下操作：

1. 在主导航窗格中，选择**文档**，然后选择**创建文档部分**。

1. 对于**文档类型**，选择**请求正文**。

1. 对于**路径**，输入请求正文的路径。

1. 对于**方法**，选择 HTTP 动词。

1. 在文本编辑器中输入描述。

1. 选择**创建文档部分**。您可以为未列出的请求正文创建文档。

1.  如果需要，请重复上述步骤，以添加或编辑另一个文档部分。

要编辑现有文档部分，请执行以下操作：

1. 在**文档**窗格中，选择**资源和方法**选项卡。

1. 您可以选择请求正文或选择包含请求正文的资源，然后使用搜索栏查找并选择您的文档部分。

1. 选择**编辑**。

## 记录 `RESPONSE` 实体
<a name="api-gateway-document-api-add-document-part-for-response-with-console"></a>

 要为 `RESPONSE` 实体添加新的文档部分，请执行以下操作：

1. 在主导航窗格中，选择**文档**，然后选择**创建文档部分**。

1. 对于**文档类型**，选择**响应(状态代码)**。

1. 对于**路径**，输入响应的路径。

1. 对于**方法**，选择 HTTP 动词。

1. 对于**状态代码**，输入 HTTP 状态代码。

1. 在文本编辑器中输入描述。

1. 选择**创建文档部分**。您可以为未列出的响应状态代码创建文档。

1.  如果需要，请重复上述步骤，以添加或编辑另一个文档部分。

要编辑现有文档部分，请执行以下操作：

1. 在**文档**窗格中，选择**资源和方法**选项卡。

1. 您可以选择响应状态代码或选择包含响应状态代码的资源，然后使用搜索栏查找并选择您的文档部分。

1. 选择**编辑**。

## 记录 `RESPONSE_HEADER` 实体
<a name="api-gateway-document-api-add-document-part-for-response-header-entity-with-console"></a>

 要为 `RESPONSE_HEADER` 实体添加新的文档部分，请执行以下操作：

1. 在主导航窗格中，选择**文档**，然后选择**创建文档部分**。

1. 对于**文档类型**，选择**响应标头**。

1. 对于**路径**，输入响应标头的路径。

1. 对于**方法**，选择 HTTP 动词。

1. 对于**状态代码**，输入 HTTP 状态代码。

1. 在文本编辑器中输入描述。

1. 选择**创建文档部分**。您可以为未列出的响应标头创建文档。

1.  如果需要，请重复上述步骤，以添加或编辑另一个文档部分。

要编辑现有文档部分，请执行以下操作：

1. 在**文档**窗格中，选择**资源和方法**选项卡。

1. 您可以选择响应标头或选择包含响应标头的资源，然后使用搜索栏查找并选择您的文档部分。

1. 选择**编辑**。

## 记录 `RESPONSE_BODY` 实体
<a name="api-gateway-document-api-add-document-part-for-response-body-entity-with-console"></a>

 要为 `RESPONSE_BODY` 实体添加新的文档部分，请执行以下操作：

1. 在主导航窗格中，选择**文档**，然后选择**创建文档部分**。

1. 对于**文档类型**，选择**响应正文**。

1. 对于**路径**，输入响应正文的路径。

1. 对于**方法**，选择 HTTP 动词。

1. 对于**状态代码**，输入 HTTP 状态代码。

1. 在文本编辑器中输入描述。

1. 选择**创建文档部分**。您可以为未列出的响应正文创建文档。

1.  如果需要，请重复上述步骤，以添加或编辑另一个文档部分。

要编辑现有文档部分，请执行以下操作：

1. 在**文档**窗格中，选择**资源和方法**选项卡。

1. 您可以选择响应正文或选择包含响应正文的资源，然后使用搜索栏查找并选择您的文档部分。

1. 选择**编辑**。

## 记录 `MODEL` 实体
<a name="api-gateway-document-api-add-document-part-for-model-entity-with-console"></a>

记录 `MODEL` 实体的过程涉及创建和管理模型的 `DocumentPart` 实例以及每个模型的 `properties`。例如，对于每个 API 默认附带的 `Error` 模型，它包含以下架构定义，

```
{
  "$schema" : "http://json-schema.org/draft-04/schema#",
  "title" : "Error Schema",
  "type" : "object",
  "properties" : {
    "message" : { "type" : "string" }
  }
}
```

 且需要两个 `DocumentationPart` 实例，其中一个用于 `Model`，另一个用于其 `message` 属性：

```
{
  "location": {
    "type": "MODEL",
    "name": "Error"
  },
  "properties": {
    "title": "Error Schema",
    "description": "A description of the Error model"
  }
}
```

和

```
{
  "location": {
    "type": "MODEL",
    "name": "Error.message"
  },
  "properties": {
    "description": "An error message."
  }
}
```

导出 API 后，`DocumentationPart` 的属性将覆盖原始架构中的值。

 要为 `MODEL` 实体添加新的文档部分，请执行以下操作：

1. 在主导航窗格中，选择**文档**，然后选择**创建文档部分**。

1. 对于**文档类型**，选择**模型**。

1. 对于**名称**，输入模型的名称。

1. 在文本编辑器中输入描述。

1. 选择**创建文档部分**。您可以为未列出的模型创建文档。

1.  如果需要，请重复上述步骤，以将文档部分添加到其他模型，或编辑文档部分。

要在**模型**窗格中为 `MODEL` 实体添加新的文档部分，请执行以下操作：

1. 在主导航窗格中，选择**模型**。

1. 选择模型，然后选择**更新文档**。

      
![\[在 API Gateway 控制台中为模型实体编辑文档\]](http://docs.aws.amazon.com/zh_cn/apigateway/latest/developerguide/images/document-model-entity-using-new-console.png)

要编辑现有文档部分，请执行以下操作：

1. 在**文档**窗格中，选择**模型**选项卡。

1. 使用搜索栏或选择模型，然后选择**编辑**。

## 记录 `AUTHORIZER` 实体
<a name="api-gateway-document-api-add-document-part-for-authorizer-entity-with-console"></a>

 要为 `AUTHORIZER` 实体添加新的文档部分，请执行以下操作：

1. 在主导航窗格中，选择**文档**，然后选择**创建文档部分**。

1. 对于**文档类型**，选择**授权方**。

1. 对于**名称**，输入授权方的名称。

1. 在文本编辑器中输入描述。为授权方的有效 `location` 字段指定一个值。

1. 选择**创建文档部分**。您可以为未列出的授权方创建文档。

1.  如果需要，请重复上述步骤，以将文档部分添加到其他授权方，或编辑文档部分。

要编辑现有文档部分，请执行以下操作：

1. 在**文档**窗格中，选择**授权方**选项卡。

1. 使用搜索栏或选择授权方，然后选择**编辑**。