# API 文档在 API Gateway 中的表示形式
<a name="api-gateway-documenting-api-content-representation"></a>

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

在 API Gateway 中，文档部分以 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 资源表示。整个 API 文档以 [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationParts.html) 集合表示。

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

**Topics**
+ [文档部分](#api-gateway-documenting-api-content-representation-documentation-parts)
+ [文档版本](#api-gateway-documenting-api-content-representation-documentation-versions)

## 文档部分
<a name="api-gateway-documenting-api-content-representation-documentation-parts"></a>

[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 资源是一个 JSON 对象，存储着适用于各个 API 实体的文档内容。这包括文档的所有 UTF-8 内容和所有主要本地化语言。它的 `properties` 字段包含作为键/值对映射的文档内容。它的 `location` 属性用于标识关联的 API 实体。

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

`DocumentationPart` 资源支持内容继承：API 实体的文档内容适用于该 API 实体的子级。有关子实体和内容继承的定义的更多信息，请参阅[从包含更通用规格的 API 实体中继承内容](#api-gateway-documenting-api-content-inheritance)。

### 文档部分的位置
<a name="api-gateway-documenting-api-content-representation-documentation-parts-target"></a>

[DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 实例的 [location](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#location) 属性用于标识要将关联内容应用于哪个 API 实体。API 实体可以是 API Gateway REST API 资源，例如 [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)、[Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)、[Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html)、[MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html)、[Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) 或 [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html)。实体也可以是消息参数，例如 URL 路径参数、查询字符串参数、请求或响应标头参数、请求或响应正文或响应状态代码。

要指定一个 API 实体，请将 `location` 对象的 [type](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#type) 属性设置为 `API`、`AUTHORIZER`、`MODEL`、`RESOURCE`、`METHOD`、`PATH_PARAMETER`、`QUERY_PARAMETER`、`REQUEST_HEADER`、`REQUEST_BODY`、`RESPONSE`、`RESPONSE_HEADER` 或 `RESPONSE_BODY` 中的一个。

根据 API 实体的 `type`，您可以指定其他 `location` 属性，包括 [method](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#method)、[name](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#name)、[path](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#path) 和 [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#statusCode)。并非所有这些属性都对给定 API 实体有效。举例来说，`type`、`path`、`name` 和 `statusCode` 是 `RESPONSE` 实体的有效属性；仅 `type` 和 `path` 是 `RESOURCE` 实体的有效位置属性。在 `location` 的 `DocumentationPart` 中为给定 API 实体添加无效字段的操作是错误的。

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

### 文档部分的内容
<a name="api-gateway-documenting-api-content-representation-documentation-parts-content"></a>

`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 识别的属性。在上一示例中，`info`、`description` 和 `x-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...",
    }
}
```

在这里，`type` 和 `path` 均为有效字段，用于识别 `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 实体中继承内容
<a name="api-gateway-documenting-api-content-inheritance"></a>

可选 `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 | \$1 | id |  与此位置模式关联的文档将由与该位置模式匹配的实体继承。  | 
| 2 | /pets | 200 | id |  当案例 1 和案例 2 相匹配时，由于案例 2 比案例 1 更具体，与此位置模式关联的文档将由与该位置模式匹配的实体继承。  | 
| 3 | /pets/petId | \$1 | 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` 的有效位置字段
<a name="api-gateway-documenting-api-content-representation-target-specification"></a>

下表显示与给定 API 实体类型关联的 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 资源的有效及必需字段和适用的默认值。


| API 实体 | 有效位置字段 | 必需位置字段 | 默认字段值 | 是否为可继承的内容 | 
| --- | --- | --- | --- | --- | 
| [ API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) |  <pre>{<br />    "location": {<br />        "type": "API" <br />    }, <br />    ... <br />}</pre>  | type | 不适用 | 否 | 
| [资源](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)： |  <pre>{ <br />    "location": { <br />        "type": "RESOURCE", <br />        "path": "resource_path" <br />    }, <br />    ... <br />}</pre>  | type | path 的默认值为 /。 | 否 | 
| [方法](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) |  <pre>{ <br />    "location": { <br />        "type": "METHOD", <br />        "path": "resource_path", <br />        "method": "http_verb" <br />    }, <br />    ... <br />}</pre>  | type | path 和 method 的默认值分别为 / 和 \$1。 | 是，按前缀匹配 path，匹配任何值的 method。 | 
| 查询参数 |  <pre>{ <br />    "location": { <br />        "type": "QUERY_PARAMETER", <br />        "path": "resource_path", <br />        "method": "HTTP_verb",<br />        "name": "query_parameter_name" <br />    }, <br />    ... <br />}</pre>  | type | path 和 method 的默认值分别为 / 和 \$1。 | 是，按前缀匹配 path，按精确值匹配 method。 | 
| 请求正文 |  <pre>{ <br />    "location": { <br />        "type": "REQUEST_BODY", <br />        "path": "resource_path", <br />        "method": "http_verb" <br />    }, <br />    ... <br />}</pre>  | type | path 和 method 的默认值分别为 / 和 \$1。 | 是，按前缀匹配 path，按精确值匹配 method。 | 
| 请求标头参数 |  <pre>{ <br />    "location": { <br />        "type": "REQUEST_HEADER", <br />        "path": "resource_path", <br />        "method": "HTTP_verb",<br />        "name": "header_name" <br />    }, <br />    ... <br />}</pre>  | type, name | path 和 method 的默认值分别为 / 和 \$1。 | 是，按前缀匹配 path，按精确值匹配 method。 | 
| 请求路径参数 |  <pre>{ <br />    "location": { <br />        "type": "PATH_PARAMETER", <br />        "path": "resource/{path_parameter_name}", <br />        "method": "HTTP_verb",<br />        "name": "path_parameter_name" <br />    }, <br />    ... <br />}</pre>  | type, name | path 和 method 的默认值分别为 / 和 \$1。 | 是，按前缀匹配 path，按精确值匹配 method。 | 
| 响应 |  <pre>{ <br />    "location": { <br />        "type": "RESPONSE", <br />        "path": "resource_path", <br />        "method": "http_verb", <br />        "statusCode": "status_code" <br />    }, <br />    ... <br />}</pre>  | type | path、method 和 statusCode 的默认值分别为 /、\$1 和 \$1。 | 是，按前缀匹配 path，按精确值匹配 method 和 statusCode。 | 
| 响应标头 |  <pre>{ <br />    "location": { <br />        "type": "RESPONSE_HEADER", <br />        "path": "resource_path", <br />        "method": "http_verb", <br />        "statusCode": "status_code", <br />        "name": "header_name" <br />    }, <br />    ... <br />}</pre>  | type, name | path、method 和 statusCode 的默认值分别为 /、\$1 和 \$1。 | 是，按前缀匹配 path，按精确值匹配 method 和 statusCode。 | 
| 响应正文 |  <pre>{ <br />    "location": { <br />        "type": "RESPONSE_BODY", <br />        "path": "resource_path", <br />        "method": "http_verb", <br />        "statusCode": "status_code" <br />    }, <br />    ... <br />}</pre>  | type | path、method 和 statusCode 的默认值分别为 /、\$1 和 \$1。 | 是，按前缀匹配 path，按精确值匹配 method 和 statusCode。 | 
| [授权方](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) |  <pre>{ <br />    "location": { <br />        "type": "AUTHORIZER", <br />        "name": "authorizer_name" <br />    }, <br />    ... <br />}</pre>  | type | 不适用 | 否 | 
| [模型](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) |  <pre>{ <br />    "location": { <br />        "type": "MODEL", <br />        "name": "model_name" <br />    }, <br />    ... <br />}</pre>  | type | 不适用 | 否 | 

## 文档版本
<a name="api-gateway-documenting-api-content-representation-documentation-versions"></a>

文档版本是 API 的 [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 集合的快照，标记有版本标识符。发布 API 文档的过程涉及创建一个文档版本，将其与一个 API 阶段关联，并将特定于阶段的 API 文档版本导出为外部 OpenAPI 文件。在 API Gateway 中，文档快照表示为 [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) 资源。

当您更新 API 时，您便创建了 API 的新版本。在 API Gateway 中，您使用 [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) 集合维护所有文档版本。