使用 API Gateway 控制台记录 API

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

创建和编辑 API 文档的一个先决条件是您必须已创建 API。在本节中，我们使用 PetStore API 作为示例。要使用 API Gateway 控制台创建 API，请按照 教程：通过导入示例创建 REST API中的说明操作。

记录 API 实体

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

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

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

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

   {
     "info": {
       "description": "Your first API Gateway API.",
       "contact": {
           "name": "John Doe",
           "email": "[e-mail]"
       }
     }
   }

   注意

   您无需将 properties 映射编码成 JSON 字符串。API Gateway 控制台会对 JSON 对象进行字符串化。

3. 选择创建文档部分。

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

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

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

   

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

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

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

记录 RESOURCE 实体

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

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

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

3. 对于路径，输入路径。

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

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

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

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

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

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

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

   

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

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

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

记录 METHOD 实体

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

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

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

3. 对于路径，输入路径。

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

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

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

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

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

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

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

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

   

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

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

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

3. 选择编辑。

记录 QUERY_PARAMETER 实体

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

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

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

3. 对于路径，输入路径。

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

5. 对于名称，输入名称。

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

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

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

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

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

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

3. 选择编辑。

记录 PATH_PARAMETER 实体

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

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

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

3. 对于路径，输入路径。

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

5. 对于名称，输入名称。

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

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

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

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

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

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

3. 选择编辑。

记录 REQUEST_HEADER 实体

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

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

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

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

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

5. 对于名称，输入名称。

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

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

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

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

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

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

3. 选择编辑。

记录 REQUEST_BODY 实体

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

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

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

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

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

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

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

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

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

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

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

3. 选择编辑。

记录 RESPONSE 实体

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

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

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

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

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

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

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

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

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

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

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

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

3. 选择编辑。

记录 RESPONSE_HEADER 实体

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

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

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

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

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

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

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

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

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

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

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

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

3. 选择编辑。

记录 RESPONSE_BODY 实体

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

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

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

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

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

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

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

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

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

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

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

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

3. 选择编辑。

记录 MODEL 实体

记录 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. 在主导航窗格中，选择文档，然后选择创建文档部分。

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

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

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

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

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

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

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

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

   

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

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

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

记录 AUTHORIZER 实体

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

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

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

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

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

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

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

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

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

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