Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

使用 API Gateway 控制台记录 API

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

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

记录 API 实体

要为 API 实体添加文档部分,请从 PetStore API 中选择 Resources。选择 Actions → Edit API Documentation 菜单项。

 在 API Gateway 控制台中为 API 实体编辑文档

如果尚未为 API 创建文档部分,您将看到文档部分的 properties 映射编辑器。在文本编辑器中键入以下 properties 映射,然后选择 Save,以创建文档部分。

{ "info": { "description": "Your first API Gateway API.", "contact": { "name": "John Doe", "email": "john.doe@api.com" } } }

注意

您未将 properties 映射编码为 JSON 字符串,这是您在使用 API Gateway REST API 时必须执行的操作。API Gateway 控制台会对 JSON 对象进行字符串化。

 在 API Gateway 控制台中编辑 API 实体的文档属性映射

如果已创建文档部分,您首先会看到 properties 映射查看器,如下所示。

 在 API Gateway 控制台中查看 API 实体的文档属性映射

如前面所示,选择 Edit 后将启动 properties 映射编辑器。

记录 RESOURCE 实体

要为 API 根资源添加或编辑文档部分,请选择 Resource 树下的 /,然后选择 Actions → Edit Resource Documentation 菜单项。

如果尚未为此实体创建文档部分,您将看到 Documentation 窗口。在编辑器中键入有效的 properties 映射。然后依次选择 SaveClose

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

如果已为 RESOURCE 实体定义文档部分,您将看到文档查看器。选择 Edit 以打开 Documentation 编辑器。修改现有的 properties 映射。选择 Save,然后选择 Close

如有必要,请重复上述步骤,将文档部分添加到其他 RESOURCE 实体。

记录 METHOD 实体

要将根资源上的 GET 方法用作示例来为 METHOD 实体添加或编辑文档,请选择 / 资源下的 GET,然后选择 Actions → Edit Method Documentation 菜单项。

对于新的文档部分,请在 Documentation 窗口的 Documentation 编辑器中键入以下 properties 映射。然后依次选择 SaveClose

{ "tags" : [ "pets" ], "description" : "PetStore HTML web page containing API usage information" }

对于现有的文档,请在 Documentation 查看器中选择 Edit。在 Documentation 编辑器中编辑文档内容,然后选择 Save。选择 Close

Documentation 查看器中,您还可以删除文档部分。

如有必要,请重复上述步骤,以将文档部分添加到其他方法。

记录 QUERY_PARAMETER 实体

要将 GET /pets?type=...&page=... 方法用作示例来为请求查询参数添加或编辑文档部分,请从 Resources 树中的 /pets 下选择 GET。在 Method Execution 窗口中选择 Method Request。展开 URL Query String Parameters 部分。举例来说,选择 page 查询参数,然后选择图书图标以打开 Documentation 查看器或编辑器。

 在 API Gateway 控制台中为 API 实体编辑文档

或者,您可以在主导航窗格的 PetStore API 下选择 Documentation。然后,为 Type 选择 Query Parameter。对于 PetStore 示例 API,这将显示 pagetype 查询参数的文档部分。

 在 API Gateway 控制台中为 API 实体编辑文档

对于为其他方法定义了查询参数的 API,您可以通过以下方式筛选您的选择:为 Path 指定受影响资源的 path,从 Method 中选择所需的 HTTP 方法,或在 Name 中键入查询参数名称。

例如,选择 page 查询参数。选择 Edit,以修改现有的文档。选择 Save 以保存更改。

要为 QUERY_PARAMETER 实体添加新的文档部分,请选择 Create Documentation Part。为 Type 选择 Query Parameter。在 Path 中键入一个资源路径 (例如 /pets)。为 Method 选择 HTTP 动词 (例如 GET)。在文本编辑器中键入 properties 描述。然后选择 Save

如有必要,请重复上述步骤,将文档部分添加到其他请求查询参数。

记录 PATH_PARAMETER 实体

要为路径参数添加或编辑文档,请转到路径参数指定的资源上方法的 Method Request。展开 Request Paths 部分。选择路径参数的图书图标,以打开 Documentation 查看器或编辑器。添加或修改文档部分的属性。

或者,在主导航窗格的 PetStore API 下选择 Documentation。为 Type 选择 Path Parameter。在列表的路径参数上,选择 Edit。修改内容,然后选择 Save

要为未列出的路径参数添加文档,请选择 Create Documentation Part。为 Type 选择 Path Parameter。在 Path 中设置资源路径,从 Method 中选择一个方法,然后在 Name 中设置路径参数名称。添加文档的属性,然后选择 Save

如果需要,请重复上述步骤,将文档部分添加到其他路径参数,或编辑文档部分。

记录 REQUEST_HEADER 实体

要为请求标头添加或编辑文档,请转到带有标头参数的方法的 Method Request。展开 HTTP Request Headers 部分。选择标头的图书图标,以打开 Documentation 查看器或编辑器。添加或修改文档部分的属性。

或者,在主导航窗格的 API 下选择 Documentation。然后,为 Type 选择 Request Header。对列出的请求标头选择 Edit 以更改文档。要为未列出的请求标头添加文档,请选择 Create Documentation Part。为 Type 选择 Request Header。在 Path 中指定资源路径。为 Method 选择方法。在 Name 中键入标头名称。然后添加并保存 properties 映射。

如果需要,请重复上述步骤,以将文档部分添加到其他请求标头,或编辑文档部分。

记录 REQUEST_BODY 实体

要为请求正文添加或编辑文档,请转到方法的 Method Request。选择 Request Body 的图书图标,以依次打开 Documentation 查看器和编辑器。添加或修改文档部分的属性。

或者,在主导航窗格的 API 下选择 Documentation。然后,为 Type 选择 Request Body。对列出的请求正文选择 Edit 以更改文档。要为未列出的请求正文添加文档,请选择 Create Documentation Part。为 Type 选择 Request Body。在 Path 中设置资源路径。为 Method 选择 HTTP 动词。然后添加并保存 properties 映射。

如果需要,请重复上述步骤,以将文档部分添加到其他请求正文,或编辑文档部分。

记录 RESPONSE 实体

要为响应添加或编辑文档,请转到方法的 Method Response。选择 Method Response 的图书图标,以依次打开 Documentation 查看器和编辑器。添加或修改文档部分的属性。

 在 API Gateway 控制台中为 RESPONSE 实体编辑文档

或者,在主导航窗格的 API 下选择 Documentation。然后,为 Type 选择 Response (status code)。对列出的指定 HTTP 状态代码的响应选择 Edit,以更改文档。要为未列出的响应正文添加文档,请选择 Create Documentation Part。为 Type 选择 Response (status code)。在 Path 中设置资源路径。为 Method 选择 HTTP 动词。在 Status Code 中键入 HTTP 状态代码。然后,添加并保存文档部分属性。

如果需要,请重复上述步骤,以将文档部分添加到其他响应,或编辑文档部分。

记录 RESPONSE_HEADER 实体

要为响应标头添加或编辑文档,请转到方法的 Method Response。展开给定 HTTP 状态的响应部分。在 Response Headers for StatusCode 下选择响应标头的图书图标,以依次打开 Documentation 查看器和编辑器。添加或修改文档部分的属性。

或者,在主导航窗格的 API 下选择 Documentation。然后,为 Type 选择 Response Header。对列出的响应标头选择 Edit,以更改文档。要为未列出的响应标头添加文档,请选择 Create Documentation Part。为 Type 选择 Response Header。在 Path 中设置资源路径。为 Method 选择 HTTP 动词。在 Status Code 中键入 HTTP 状态代码。在 Name 中键入响应标头名称。然后,添加并保存文档部分属性。

如果需要,请重复上述步骤,以将文档部分添加到其他响应标头,或编辑文档部分。

记录 RESPONSE_BODY 实体

要为响应正文添加或编辑文档,请转到方法的 Method Response。展开给定 HTTP 状态的响应部分。选择 Response Body for StatusCode 的图书图标,以依次打开 Documentation 查看器和编辑器。添加或修改文档部分的属性。

或者,在主导航窗格的 API 下选择 Documentation。然后,为 Type 选择 Response Body。对列出的响应正文选择 Edit,以更改文档。要为未列出的响应正文添加文档,请选择 Create Documentation Part。为 Type 选择 Response Body。在 Path 中设置资源路径。为 Method 选择 HTTP 动词。在 Status Code 中键入 HTTP 状态代码。然后,添加并保存文档部分属性。

如果需要,请重复上述步骤,以将文档部分添加到其他响应正文,或编辑文档部分。

记录 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 的属性将覆盖原始架构中的值。

要为模型添加或编辑文档,请转到主导航窗格中 API 的 Models。选择列出模型的名称对应的图书图标,以依次打开 Documentation 查看器和编辑器。添加或修改文档部分的属性。

或者,在主导航窗格的 API 下选择 Documentation。然后,为 Type 选择 Model。对列出的模型选择 Edit,以更改文档。要为未列出的模型添加文档,请选择 Create Documentation Part。为 Type 选择 Model。在 Name 中为模型指定名称。然后,添加并保存文档部分属性。

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

记录 AUTHORIZER 实体

要为授权方添加或编辑文档,请转到主导航窗格中 API 的 Authorizers。选择列出的授权方对应的图书图标,以依次打开 Documentation 查看器和编辑器。添加或修改文档部分的属性。

或者,在主导航窗格的 API 下选择 Documentation。然后,为 Type 选择 Authorizer。对列出的授权方选择 Edit,以更改文档。要为未列出的授权方添加文档,请选择 Create Documentation Part。为 Type 选择 Authorizer。在 Name 中为授权方指定名称。然后,添加并保存文档部分属性。

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

要为授权方添加文档部分,请选择 Create Documentation Part。为 Type 选择 Authorizer。在 Name 的有效 location 字段中为授权方指定一个值。

properties 映射编辑器中添加并保存文档内容。

如果需要,请重复上述步骤,以将文档部分添加到另一个授权方。