API 文档在 API Gateway 中的表示形式 - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

API 文档在 API Gateway 中的表示形式

API Gateway API 文档包含多个与特定 API 实体关联的独立文档部分,其中包括 API、资源、方法、请求、响应、消息参数(即路径、查询、标头),以及授权方和模型。

在 API Gateway 中,文档部分以 DocumentationPart 资源表示。整个 API 文档以 DocumentationParts 集合表示。

记录 API 的过程涉及创建 DocumentationPart 实例,将其添加至 DocumentationParts 集合,以及随着 API 的发展维护文档部分的各个版本。

文档部分

DocumentationPart 资源是一个 JSON 对象,存储着适用于各个 API 实体的文档内容。它的 properties 字段包含作为键/值对映射的文档内容。它的 location 属性用于标识关联的 API 实体。

内容映射的形状由您 (API 开发人员) 决定。键/值对的值可以是字符串、数字、布尔值、对象或数组。location 对象的形状取决于目标实体类型。

DocumentationPart 资源支持内容继承:API 实体的文档内容适用于该 API 实体的子级。有关子实体和内容继承的定义的更多信息,请参阅从包含更通用规格的 API 实体中继承内容

文档部分的位置

DocumentationPart 实例的 location 属性用于标识要将关联内容应用于哪个 API 实体。API 实体可以是 API Gateway REST API 资源,例如 RestApiResourceMethodMethodResponseAuthorizerModel。实体也可以是消息参数,例如 URL 路径参数、查询字符串参数、请求或响应标头参数、请求或响应正文或响应状态代码。

要指定一个 API 实体,请将 location 对象的 type 属性设置为 APIAUTHORIZERMODELRESOURCEMETHODPATH_PARAMETERQUERY_PARAMETERREQUEST_HEADERREQUEST_BODYRESPONSERESPONSE_HEADERRESPONSE_BODY 中的一个。

根据 API 实体的 type,您可以指定其他 location 属性,包括 methodnamepathstatusCode。并非所有这些属性都对给定 API 实体有效。举例来说,typepathnamestatusCodeRESPONSE 实体的有效属性;仅 typepathRESOURCE 实体的有效位置属性。在 locationDocumentationPart 中为给定 API 实体添加无效字段的操作是错误的。

并非所有有效的 location 字段都是必需字段。例如,type 是所有 API 实体的有效和必需 location 字段。但是,methodpathstatusCodeRESPONSE 实体的有效属性,却并非必需属性。在未明确规定时,有效的 location 字段将作为其默认值。默认的 path 值为 /,即 API 的根资源。methodstatusCode 的默认值为 *,分别表示任意方法值或任意状态代码值。

文档部分的内容

properties 值以 JSON 字符串的格式编码。properties 值包含您为满足文档要求而选择的任何信息。例如,以下是一个有效的内容映射:

{ "info": { "description": "My first API with Amazon API Gateway." }, "x-custom-info" : "My custom info, recognized by OpenAPI.", "my-info" : "My custom info not recognized by OpenAPI." }

虽然 API Gateway 接受将任意有效 JSON 字符串作为内容映射,但内容属性仍分为两类:可以被 OpenAPI 识别的属性以及不可被 OpenAPI 识别的属性。在上一示例中,infodescriptionx-custom-info 均被 OpenAPI 识别为标准 OpenAPI 对象、属性或扩展。相比之下,my-info 不符合 OpenAPI 规范。API Gateway 会将符合 OpenAPI 规范的内容属性从关联的 DocumentationPart 实例传播到 API 实体定义中。API Gateway 不会将不符合规范的内容属性传播到 API 实体定义中。

再给一个示例,以下是面向 DocumentationPart 实体的 Resource

{ "location" : { "type" : "RESOURCE", "path": "/pets" }, "properties" : { "summary" : "The /pets resource represents a collection of pets in PetStore.", "description": "... a child resource under the root...", } }

在这里,typepath 均为有效字段,用于识别 RESOURCE 类型的目标。对于根资源 (/),您可以省略 path 字段。

{ "location" : { "type" : "RESOURCE" }, "properties" : { "description" : "The root resource with the default path specification." } }

以下 DocumentationPart 实例也是如此:

{ "location" : { "type" : "RESOURCE", "path": "/" }, "properties" : { "description" : "The root resource with an explicit path specification" } }

从包含更通用规格的 API 实体中继承内容

可选 location 字段的默认值提供了 API 实体的模式化描述。使用 location 对象中的默认值,您可以通过这类 properties 模式,在到 DocumentationPart 实例的 location 映射中添加一般性描述。API Gateway 从通用 API 实体的 DocumentationPart 中提取适用的 OpenAPI 文档属性,并通过与一般 location 模式匹配或与精确值匹配的 location 字段将其注入特定 API 实体中,除非特定实体已拥有与其关联的 DocumentationPart 实例。此行为也称为从包含更通用规格的 API 实体中继承内容。

内容继承不适用于某些 API 实体类型。有关详细信息,请参阅下表。

当 API 实体与多个 DocumentationPart 的位置模式匹配时,该实体将继承具有最高优先级和特定性的位置字段的文档部分。优先顺序是 path > statusCode。为与 path 字段匹配,API Gateway 会选择拥有最具体的路径值的实体。下表通过几个示例展示了这一点。

案例 path statusCode name 备注
1 /pets * id

与此位置模式关联的文档将由与该位置模式匹配的实体继承。

2 /pets 200 id

当案例 1 和案例 2 相匹配时,由于案例 2 比案例 1 更具体,与此位置模式关联的文档将由与该位置模式匹配的实体继承。

3 /pets/petId * id

当案例 1、2 和案例 3 匹配时,由于案例 3 的优先级比案例 2 高,并且比案例 1 更具体,与此位置模式关联的文档将由与该位置模式匹配的实体继承。

以下是另一个示例,它对比了更通用的 DocumentationPart 实例与更具体的实例。以下一般性错误消息 "Invalid request error" 已注入 400 错误响应的 OpenAPI 定义中(除非被覆盖)。

{ "location" : { "type" : "RESPONSE", "statusCode": "400" }, "properties" : { "description" : "Invalid request error." }" }

通过以下覆盖,对 400 资源上任何方法的 /pets 响应都会改为 "Invalid petId specified" 这一描述。

{ "location" : { "type" : "RESPONSE", "path": "/pets", "statusCode": "400" }, "properties" : "{ "description" : "Invalid petId specified." }" }

DocumentationPart 的有效位置字段

下表显示与给定 API 实体类型关联的 DocumentationPart 资源的有效及必需字段和适用的默认值。

API 实体

有效位置字段

必需位置字段 默认字段值 是否为可继承的内容
API
{ "location": { "type": "API" }, ... }
type 不适用
资源
{ "location": { "type": "RESOURCE", "path": "resource_path" }, ... }
type path 的默认值为 /
方法
{ "location": { "type": "METHOD", "path": "resource_path", "method": "http_verb" }, ... }
type pathmethod 的默认值分别为 /* 是,按前缀匹配 path,匹配任何值的 method
查询参数
{ "location": { "type": "QUERY_PARAMETER", "path": "resource_path", "method": "HTTP_verb", "name": "query_parameter_name" }, ... }
type pathmethod 的默认值分别为 /* 是,按前缀匹配 path,按精确值匹配 method
请求正文
{ "location": { "type": "REQUEST_BODY", "path": "resource_path", "method": "http_verb" }, ... }
type pathmethod 的默认值分别为 /* 是,按前缀匹配 path,按精确值匹配 method
请求标头参数
{ "location": { "type": "REQUEST_HEADER", "path": "resource_path", "method": "HTTP_verb", "name": "header_name" }, ... }
type, name pathmethod 的默认值分别为 /* 是,按前缀匹配 path,按精确值匹配 method
请求路径参数
{ "location": { "type": "PATH_PARAMETER", "path": "resource/{path_parameter_name}", "method": "HTTP_verb", "name": "path_parameter_name" }, ... }
type, name pathmethod 的默认值分别为 /* 是,按前缀匹配 path,按精确值匹配 method
响应
{ "location": { "type": "RESPONSE", "path": "resource_path", "method": "http_verb", "statusCode": "status_code" }, ... }
type pathmethodstatusCode 的默认值分别为 /** 是,按前缀匹配 path,按精确值匹配 methodstatusCode
响应标头
{ "location": { "type": "RESPONSE_HEADER", "path": "resource_path", "method": "http_verb", "statusCode": "status_code", "name": "header_name" }, ... }
type, name pathmethodstatusCode 的默认值分别为 /** 是,按前缀匹配 path,按精确值匹配 methodstatusCode
响应正文
{ "location": { "type": "RESPONSE_BODY", "path": "resource_path", "method": "http_verb", "statusCode": "status_code" }, ... }
type pathmethodstatusCode 的默认值分别为 /** 是,按前缀匹配 path,按精确值匹配 methodstatusCode
授权方
{ "location": { "type": "AUTHORIZER", "name": "authorizer_name" }, ... }
type 不适用
模型
{ "location": { "type": "MODEL", "name": "model_name" }, ... }
type 不适用

文档版本

文档版本是 API 的 DocumentationParts 集合的快照,标记有版本标识符。发布 API 文档的过程涉及创建一个文档版本,将其与一个 API 阶段关联,并将特定于阶段的 API 文档版本导出为外部 OpenAPI 文件。在 API Gateway 中,文档快照表示为 DocumentationVersion 资源。

当您更新 API 时,您便创建了 API 的新版本。在 API Gateway 中,您使用 DocumentationVersions 集合维护所有文档版本。