# Representação da documentação da API no API Gateway
<a name="api-gateway-documenting-api-content-representation"></a>

A documentação de API do API Gateway consiste em partes de documentação individuais associadas a entidades de API específicas que incluem API, recurso, método, solicitação, resposta, parâmetros de mensagem (ou seja, caminho, consulta, cabeçalho), bem como autorizadores e modelos. 

No API Gateway, uma parte de documentação é representada por um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html). A documentação da API como um todo é representada pela coleção [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationParts.html). 

Documentar uma API envolve criar instâncias de `DocumentationPart`, adicioná-las à coleção `DocumentationParts` e manter versões das partes de documentação à medida que a sua API evolui.

**Topics**
+ [Partes da documentação](#api-gateway-documenting-api-content-representation-documentation-parts)
+ [Versões da documentação](#api-gateway-documenting-api-content-representation-documentation-versions)

## Partes da documentação
<a name="api-gateway-documenting-api-content-representation-documentation-parts"></a>

Um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) é um objeto JSON que armazena o conteúdo da documentação aplicável a uma entidade da API individual. Isso inclui qualquer conteúdo UTF-8 e todos os principais idiomas de localização para sua documentação. Seu campo `properties` contém o conteúdo da documentação como um mapa de pares de chave/valor. Sua propriedade `location` identifica a entidade de API associada. 

A forma de um mapa de conteúdo é determinada por você, o desenvolvedor da API. O valor de um par de chave/valor pode ser uma string, número, booliano, objeto ou matriz. A forma do objeto `location` depende do tipo de entidade alvo. 

O recurso `DocumentationPart` oferece suporte para herança de conteúdo: o conteúdo da documentação de uma entidade de API é aplicável aos filhos dessa entidade de API. Para obter mais informações sobre a definição de entidades filho e herança de conteúdo, consulte [Herdar conteúdo de uma entidade de API com especificação mais geral](#api-gateway-documenting-api-content-inheritance). 

### Localização de uma parte de documentação
<a name="api-gateway-documenting-api-content-representation-documentation-parts-target"></a>

A propriedade [location](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#location) de uma instância de [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) identifica uma entidade de API à qual o conteúdo associado se aplica. A entidade de API pode ser um recurso de API REST do API Gateway, como [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) ou [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html). Ela também pode ser um parâmetro de mensagem, como um parâmetro de caminho de URL, um parâmetro de string de consulta, um parâmetro de cabeçalho de solicitação ou resposta, um corpo de solicitação ou resposta ou um código de status de resposta. 

Para especificar uma entidade da API, defina o atributo [type](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#type) do objeto `location` como um dos seguintes: `API`, `AUTHORIZER`, `MODEL`, `RESOURCE`, `METHOD`, `PATH_PARAMETER`, `QUERY_PARAMETER`, `REQUEST_HEADER`, `REQUEST_BODY`, `RESPONSE`, `RESPONSE_HEADER` ou `RESPONSE_BODY`. 

Dependendo do `type` de uma entidade da API, você pode especificar outros atributos de `location`, incluindo [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) e [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#statusCode). Nem todos esses atributos são válidos para uma determinada entidade de API. Por exemplo, `type`, `path`, `name` e `statusCode` são atributos válidos da entidade `RESPONSE`; apenas `type` e `path` são atributos de localização válidos da entidade `RESOURCE`. É um erro incluir um campo inválido no `location` de um `DocumentationPart` para uma determinada entidade de API.

Nem todos os campos válidos de `location` são necessários. Por exemplo, `type` é o campo `location` tanto válido quanto obrigatório de todas as entidades de API. No entanto, `method`, `path` e `statusCode` são atributos válidos, mas não obrigatórios, para a entidade `RESPONSE`. Quando não explicitamente especificado, um campo `location` válido assume seu valor padrão. O valor de `path` padrão é `/`, ou seja, o recurso raiz de uma API. O valor padrão de `method`, ou `statusCode`, é `*`, significando qualquer valor de método ou código de status, respectivamente.

### Conteúdo de uma parte da documentação
<a name="api-gateway-documenting-api-content-representation-documentation-parts-content"></a>

O valor de `properties` é codificado como uma string JSON. O valor de `properties` contém qualquer informação que você escolher para atender às suas necessidades de documentação. Por exemplo, o seguinte é um mapa de conteúdo válido: 

```
{
  "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."
}
```

Embora o API Gateway aceite qualquer string JSON válida como o mapa de conteúdo, os atributos de conteúdo são tratados como duas categorias: aqueles que podem ser reconhecidos pelo OpenAPI e aqueles que não podem. No exemplo anterior, `info`, `description` e `x-custom-info` são reconhecidos pelo OpenAPI como um objeto, uma propriedade ou uma extensão padrão do OpenAPI. Em contraste, `my-info` não é compatível com a especificação OpenAPI. O API Gateway propaga atributos de conteúdo compatíveis com OpenAPI para as definições de entidades de API das instâncias `DocumentationPart` associadas. O API Gateway não propaga os atributos de conteúdo não compatíveis nas definições de entidades de API. 

Como outro exemplo, aqui está uma `DocumentationPart` direcionada para uma entidade `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...",
    }
}
```

Aqui, tanto `type` quanto `path` são campos válidos para identificar o destino do tipo `RESOURCE`. Para o recurso de raiz (`/`), você pode omitir o campo `path`.

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

Isso equivale à seguinte instância de `DocumentationPart`:

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



### Herdar conteúdo de uma entidade de API com especificações mais gerais
<a name="api-gateway-documenting-api-content-inheritance"></a>

O valor padrão de um campo `location` opcional fornece uma descrição padronizada de uma entidade de API. Usando o valor padrão no objeto `location`, é possível adicionar uma descrição geral no mapa `properties` a uma instância de `DocumentationPart` com esse tipo de padrão de `location`. O API Gateway extrai os atributos da documentação do OpenAPI aplicáveis de `DocumentationPart` da entidade de API genérica e os injeta em uma entidade de API específica com os campos `location` correspondentes ao padrão `location` geral ou correspondentes ao valor exato, a menos que a entidade específica já tenha uma instância de `DocumentationPart` associada a ela. Esse comportamento também é conhecido como herança de conteúdo de uma entidade de API de especificações mais gerais. 

A herança de conteúdo não se aplica a determinados tipos de entidade de API. Consulte a tabela a seguir para obter detalhes.

Quando uma entidade de API corresponder ao padrão de localização de `DocumentationPart`, ela herdará a parte de documentação com os campos de localização de maior precedência e especificidade. A ordem de precedência é `path` > `statusCode`. Para correspondência com o campo `path`, o API Gateway escolhe a entidade com o valor do caminho mais específico. A tabela a seguir mostra isso com alguns exemplos.


| Caso | `path` | `statusCode` | `name` | Observações | 
| --- | --- | --- | --- | --- | 
| 1 | /pets | \$1 | id |  A documentação associada a esse padrão de localização será herdada por entidades que corresponderem ao padrão de localização.  | 
| 2 | /pets | 200 | id |  A documentação associada a esse padrão de localização será herdada por entidades que corresponderem ao padrão de localização quando tanto o Caso 1 quanto o Caso 2 forem correspondidos, pois o Caso 2 é mais específico do que o Caso 1.   | 
| 3 | /pets/petId | \$1 | id |  A documentação associada a esse padrão de localização será herdada por entidades que corresponderem ao padrão de localização quando os Casos 1, 2 e 3 forem correspondidos, pois o Caso 3 tem precedência maior do que o Caso 2 e é mais específico do que o Caso 1.  | 

Veja a seguir outro exemplo para contrastar uma instância mais genérica de `DocumentationPart` com uma mais específica. A seguinte mensagem de erro geral `"Invalid request error"` será injetada nas definições do OpenAPI das respostas de erro `400`, a menos que ela seja substituída. 

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

Com a seguinte substituição, as respostas `400` a qualquer método no recurso `/pets` têm uma descrição de `"Invalid petId specified"` em vez disso. 

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

### Campos de localização válidos de `DocumentationPart`
<a name="api-gateway-documenting-api-content-representation-target-specification"></a>

A seguinte tabela mostra os campos válidos e necessários, bem como valores padrão aplicáveis de um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) que está associado a um determinado tipo de entidade de API.


| Entidade de API | Campos de localização válidos | Campos de localização obrigatórios | Valores de campo padrão | Conteúdo herdável | 
| --- | --- | --- | --- | --- | 
| [solicitações de](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) |  <pre>{<br />    "location": {<br />        "type": "API" <br />    }, <br />    ... <br />}</pre>  | type | N/D | Não | 
| [Recurso](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 | O valor padrão de path é /.  | Não | 
| [Method (Método](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 | Os valores padrão de path e method são / e \$1, respectivamente.  | Sim, correspondendo path por prefixo e correspondendo method de quaisquer valores.  | 
| Parâmetro de consulta |  <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 | Os valores padrão de path e method são / e \$1, respectivamente.  | Sim, correspondendo path por prefixo e correspondendo method por valores exatos. | 
| Corpo da solicitação |  <pre>{ <br />    "location": { <br />        "type": "REQUEST_BODY", <br />        "path": "resource_path", <br />        "method": "http_verb" <br />    }, <br />    ... <br />}</pre>  | type | Os valores padrão de path e method são / e \$1, respectivamente.  | Sim, correspondendo path por prefixo e correspondendo method por valores exatos. | 
| Parâmetro do cabeçalho da solicitação |  <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 | Os valores padrão de path e method são / e \$1, respectivamente.  | Sim, correspondendo path por prefixo e correspondendo method por valores exatos. | 
| Parâmetro do caminho da solicitação |  <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 | Os valores padrão de path e method são / e \$1, respectivamente.  | Sim, correspondendo path por prefixo e correspondendo method por valores exatos. | 
| Resposta |  <pre>{ <br />    "location": { <br />        "type": "RESPONSE", <br />        "path": "resource_path", <br />        "method": "http_verb", <br />        "statusCode": "status_code" <br />    }, <br />    ... <br />}</pre>  | type | Os valores padrão de path, method e statusCode são /, \$1 e \$1, respectivamente.  | Sim, correspondendo path por prefixo e correspondendo method e statusCode por valores exatos. | 
| Cabeçalho da resposta |  <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 | Os valores padrão de path, method e statusCode são /, \$1 e \$1, respectivamente.  | Sim, correspondendo path por prefixo e correspondendo method e statusCode por valores exatos. | 
| Corpo da resposta |  <pre>{ <br />    "location": { <br />        "type": "RESPONSE_BODY", <br />        "path": "resource_path", <br />        "method": "http_verb", <br />        "statusCode": "status_code" <br />    }, <br />    ... <br />}</pre>  | type | Os valores padrão de path, method e statusCode são /, \$1 e \$1, respectivamente.  | Sim, correspondendo path por prefixo e correspondendo method e statusCode por valores exatos. | 
| [Autorizador](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 | N/D | Não | 
| [Modelo](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 | N/D | Não | 

## Versões da documentação
<a name="api-gateway-documenting-api-content-representation-documentation-versions"></a>

Uma versão de documentação é um snapshot da coleção [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de uma API e é marcada com um identificador de versão. Publicar a documentação de uma API envolve criar uma versão da documentação, associá-la a um estágio de API e exportar essa versão específica de estágio da documentação da API para um arquivo do OpenAPI externo. No API Gateway, um snapshot de documentação é representado como um recurso [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html). 

À medida que você atualiza uma API, novas versões dela são criadas. No API Gateway, todas as versões da documentação são mantidas usando a coleção [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html).