# Documentar uma API usando a API REST do API Gateway
Nesta seção, descrevemos como criar e manter partes da documentação de uma API usando a API REST do API Gateway.
Crie uma API antes de criar e editar sua documentação. Nesta seção, usamos a API [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets) como exemplo. Para criar uma API usando o console do API Gateway, siga as instruções em [Tutorial: Criar uma API REST importando um exemplo](api-gateway-create-api-from-example.md).
**Topics**
+ [Documentar a entidade `API`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-api)
+ [Documentar uma entidade `RESOURCE`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-resource)
+ [Documentar uma entidade `METHOD`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-method)
+ [Documentar uma entidade `QUERY_PARAMETER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-query-parameter)
+ [Documentar uma entidade `PATH_PARAMETER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-path-parameter)
+ [Documentar uma entidade `REQUEST_BODY`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-body)
+ [Documentar uma entidade `REQUEST_HEADER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-header)
+ [Documentar uma entidade `RESPONSE`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response)
+ [Documentar uma entidade `RESPONSE_HEADER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response-header)
+ [Documentar uma entidade `AUTHORIZER`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-authorizer)
+ [Documentar uma entidade `MODEL`](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-model)
+ [Atualizar partes da documentação](#api-gateway-documenting-api-quick-start-with-restapi-update-content)
+ [Listar partes da documentação](#api-gateway-documenting-api-quick-start-with-restapi-list-parts)
## Documentar a entidade `API`
Para adicionar documentação para uma [API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), adicione um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) à entidade de API:
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "API"
},
"properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}"
}
```
Se bem-sucedida, a operação retornará uma resposta `201 Created`, contendo a instância `DocumentationPart` recém-criada na carga útil. Por exemplo:
```
{
...
"id": "s2e5xf",
"location": {
"path": null,
"method": null,
"name": null,
"statusCode": null,
"type": "API"
},
"properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}"
}
```
Se a parte de documentação já tiver sido adicionada, será retornada uma resposta `409 Conflict` contendo a mensagem de erro `Documentation part already exists for the specified location: type 'API'."`. Nesse caso, você deve chamar a operação [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html).
```
PATCH /restapis/4wk1k4onj3/documentation/parts/part_id HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"patchOperations" : [ {
"op" : "replace",
"path" : "/properties",
"value" : "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}"
} ]
}
```
A resposta bem-sucedida retorna um código de status `200 OK` com a carga útil que contém a instância `DocumentationPart` atualizada.
## Documentar uma entidade `RESOURCE`
Para adicionar a documentação do recurso raiz de uma API, adicione um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) direcionado ao recurso [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) correspondente:
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "RESOURCE",
},
"properties" : "{\n\t\"description\" : \"The PetStore root resource.\"\n}"
}
```
Se bem-sucedida, a operação retornará uma resposta `201 Created`, contendo a instância `DocumentationPart` recém-criada na carga útil. Por exemplo:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo"
}
},
"id": "p76vqo",
"location": {
"path": "/",
"method": null,
"name": null,
"statusCode": null,
"type": "RESOURCE"
},
"properties": "{\n\t\"description\" : \"The PetStore root resource.\"\n}"
}
```
Quando o caminho do recurso não é especificado, supõe-se que esse recurso seja raiz. Você pode adicionar `"path": "/"` a `properties` para tornar a especificação explícita.
Para criar a documentação de um recurso filho de uma API, adicione um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) direcionado ao recurso [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) correspondente:
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "RESOURCE",
"path" : "/pets"
},
"properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}"
}
```
Se bem-sucedida, a operação retornará uma resposta `201 Created`, contendo a instância `DocumentationPart` recém-criada na carga útil. Por exemplo:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/qcht86"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/qcht86"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/qcht86"
}
},
"id": "qcht86",
"location": {
"path": "/pets",
"method": null,
"name": null,
"statusCode": null,
"type": "RESOURCE"
},
"properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}"
}
```
Para adicionar a documentação de um recurso filho especificado por um parâmetro de caminho, adicione um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) direcionado ao recurso [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html):
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "RESOURCE",
"path" : "/pets/{petId}"
},
"properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}"
}
```
Se bem-sucedida, a operação retornará uma resposta `201 Created`, contendo a instância `DocumentationPart` recém-criada na carga útil. Por exemplo:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb"
}
},
"id": "k6fpwb",
"location": {
"path": "/pets/{petId}",
"method": null,
"name": null,
"statusCode": null,
"type": "RESOURCE"
},
"properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}"
}
```
**nota**
A instância de [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de uma entidade `RESOURCE` não pode ser herdada por nenhum de seus recursos filho.
## Documentar uma entidade `METHOD`
Para adicionar a documentação para um método de uma API, adicione um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) direcionado ao recurso [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) correspondente:
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "METHOD",
"path" : "/pets",
"method" : "GET"
},
"properties": "{\n\t\"summary\" : \"List all pets.\"\n}"
}
```
Se bem-sucedida, a operação retornará uma resposta `201 Created`, contendo a instância `DocumentationPart` recém-criada na carga útil. Por exemplo:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
}
},
"id": "o64jbj",
"location": {
"path": "/pets",
"method": "GET",
"name": null,
"statusCode": null,
"type": "METHOD"
},
"properties": "{\n\t\"summary\" : \"List all pets.\"\n}"
}
```
Se bem-sucedida, a operação retornará uma resposta `201 Created`, contendo a instância `DocumentationPart` recém-criada na carga útil. Por exemplo:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
}
},
"id": "o64jbj",
"location": {
"path": "/pets",
"method": "GET",
"name": null,
"statusCode": null,
"type": "METHOD"
},
"properties": "{\n\t\"summary\" : \"List all pets.\"\n}"
}
```
Se o campo `location.method` não for especificado na solicitação anterior, supõe-se que ele seja o método `ANY` que é representado por um caractere curinga `*`.
Para atualizar o conteúdo de documentação de uma entidade `METHOD`, chame a operação [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html), fornecendo um novo mapa de `properties`:
```
PATCH /restapis/4wk1k4onj3/documentation/parts/part_id HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"patchOperations" : [ {
"op" : "replace",
"path" : "/properties",
"value" : "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}"
} ]
}
```
A resposta bem-sucedida retorna um código de status `200 OK` com a carga útil que contém a instância `DocumentationPart` atualizada. Por exemplo:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj"
}
},
"id": "o64jbj",
"location": {
"path": "/pets",
"method": "GET",
"name": null,
"statusCode": null,
"type": "METHOD"
},
"properties": "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}"
}
```
## Documentar uma entidade `QUERY_PARAMETER`
Para adicionar a documentação de um parâmetro de consulta de solicitação, adicione um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) direcionado ao tipo `QUERY_PARAMETER`, com os campos válidos de `path` e `name`.
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "QUERY_PARAMETER",
"path" : "/pets",
"method" : "GET",
"name" : "page"
},
"properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}"
}
```
Se bem-sucedida, a operação retornará uma resposta `201 Created`, contendo a instância `DocumentationPart` recém-criada na carga útil. Por exemplo:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w"
}
},
"id": "h9ht5w",
"location": {
"path": "/pets",
"method": "GET",
"name": "page",
"statusCode": null,
"type": "QUERY_PARAMETER"
},
"properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}"
}
```
O mapa de `properties` da parte de documentação de uma entidade `QUERY_PARAMETER` pode ser herdado por uma de suas entidades `QUERY_PARAMETER` filho. Por exemplo, se você adicionar um recurso `treats` depois de `/pets/{petId}`, habilitar o método `GET` em `/pets/{petId}/treats` e expor o parâmetro de consulta `page`, esse parâmetro de consulta filho herdará o mapa `DocumentationPart` de `properties` do parâmetro de consulta com nome semelhante do método `GET /pets`, a menos que você adicione explicitamente um recurso `DocumentationPart` ao parâmetro de consulta `page` do método `GET /pets/{petId}/treats`.
## Documentar uma entidade `PATH_PARAMETER`
Para adicionar a documentação de um parâmetro de caminho, adicione um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) para a entidade `PATH_PARAMETER`.
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "PATH_PARAMETER",
"path" : "/pets/{petId}",
"method" : "*",
"name" : "petId"
},
"properties": "{\n\t\"description\" : \"The id of the pet to retrieve.\"\n}"
}
```
Se bem-sucedida, a operação retornará uma resposta `201 Created`, contendo a instância `DocumentationPart` recém-criada na carga útil. Por exemplo:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog"
}
},
"id": "ckpgog",
"location": {
"path": "/pets/{petId}",
"method": "*",
"name": "petId",
"statusCode": null,
"type": "PATH_PARAMETER"
},
"properties": "{\n \"description\" : \"The id of the pet to retrieve\"\n}"
}
```
## Documentar uma entidade `REQUEST_BODY`
Para adicionar a documentação de um corpo de solicitação, adicione um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) para o corpo da solicitação.
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "REQUEST_BODY",
"path" : "/pets",
"method" : "POST"
},
"properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}"
}
```
Se bem-sucedida, a operação retornará uma resposta `201 Created`, contendo a instância `DocumentationPart` recém-criada na carga útil. Por exemplo:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1"
}
},
"id": "kgmfr1",
"location": {
"path": "/pets",
"method": "POST",
"name": null,
"statusCode": null,
"type": "REQUEST_BODY"
},
"properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}"
}
```
## Documentar uma entidade `REQUEST_HEADER`
Para adicionar a documentação de um cabeçalho de solicitação, adicione um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) para o cabeçalho da solicitação.
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "REQUEST_HEADER",
"path" : "/pets",
"method" : "GET",
"name" : "x-my-token"
},
"properties": "{\n\t\"description\" : \"A custom token used to authorization the method invocation.\"\n}"
}
```
Se bem-sucedida, a operação retornará uma resposta `201 Created`, contendo a instância `DocumentationPart` recém-criada na carga útil. Por exemplo:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf"
}
},
"id": "h0m3uf",
"location": {
"path": "/pets",
"method": "GET",
"name": "x-my-token",
"statusCode": null,
"type": "REQUEST_HEADER"
},
"properties": "{\n\t\"description\" : \"A custom token used to authorization the method invocation.\"\n}"
}
```
## Documentar uma entidade `RESPONSE`
Para adicionar a documentação para uma resposta de um código de status, adicione um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) direcionado para o recurso [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) correspondente.
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location": {
"path": "/",
"method": "*",
"name": null,
"statusCode": "200",
"type": "RESPONSE"
},
"properties": "{\n \"description\" : \"Successful operation.\"\n}"
}
```
Se bem-sucedida, a operação retornará uma resposta `201 Created`, contendo a instância `DocumentationPart` recém-criada na carga útil. Por exemplo:
```
{
"_links": {
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lattew"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lattew"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lattew"
}
},
"id": "lattew",
"location": {
"path": "/",
"method": "*",
"name": null,
"statusCode": "200",
"type": "RESPONSE"
},
"properties": "{\n \"description\" : \"Successful operation.\"\n}"
}
```
## Documentar uma entidade `RESPONSE_HEADER`
Para adicionar a documentação de um cabeçalho de resposta, adicione um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) para o cabeçalho da solicitação.
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
"location": {
"path": "/",
"method": "GET",
"name": "Content-Type",
"statusCode": "200",
"type": "RESPONSE_HEADER"
},
"properties": "{\n \"description\" : \"Media type of request\"\n}"
```
Se bem-sucedida, a operação retornará uma resposta `201 Created`, contendo a instância `DocumentationPart` recém-criada na carga útil. Por exemplo:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7"
}
},
"id": "fev7j7",
"location": {
"path": "/",
"method": "GET",
"name": "Content-Type",
"statusCode": "200",
"type": "RESPONSE_HEADER"
},
"properties": "{\n \"description\" : \"Media type of request\"\n}"
}
```
A documentação desse cabeçalho de resposta `Content-Type` é a documentação padrão para os cabeçalhos `Content-Type` de todas as respostas da API.
## Documentar uma entidade `AUTHORIZER`
Para adicionar a documentação de um autorizador de API, adicione um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) direcionado ao autorizador especificado.
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "AUTHORIZER",
"name" : "myAuthorizer"
},
"properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}"
}
```
Se bem-sucedida, a operação retornará uma resposta `201 Created`, contendo a instância `DocumentationPart` recém-criada na carga útil. Por exemplo:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3"
}
},
"id": "pw3qw3",
"location": {
"path": null,
"method": null,
"name": "myAuthorizer",
"statusCode": null,
"type": "AUTHORIZER"
},
"properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}"
}
```
**nota**
A instância de [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de uma entidade `AUTHORIZER` não pode ser herdada por nenhum de seus recursos filho.
## Documentar uma entidade `MODEL`
A documentação de uma entidade `MODEL` envolve a criação e o gerenciamento de instâncias de `DocumentPart` para o modelo e cada uma das `properties` do modelo. Por exemplo, o modelo `Error` que acompanha cada API por padrão tem a seguinte definição de esquema,
```
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"title" : "Error Schema",
"type" : "object",
"properties" : {
"message" : { "type" : "string" }
}
}
```
e requer duas instâncias de `DocumentationPart`, uma para o `Model` e a outra para sua propriedade `message`:
```
{
"location": {
"type": "MODEL",
"name": "Error"
},
"properties": {
"title": "Error Schema",
"description": "A description of the Error model"
}
}
```
e
```
{
"location": {
"type": "MODEL",
"name": "Error.message"
},
"properties": {
"description": "An error message."
}
}
```
Quando a API for exportada, as propriedades de `DocumentationPart` substituirão os valores no esquema original.
Para adicionar a documentação de um modelo de API, adicione um recurso [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) direcionado ao modelo especificado.
```
POST /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"location" : {
"type" : "MODEL",
"name" : "Pet"
},
"properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}"
}
```
Se bem-sucedida, a operação retornará uma resposta `201 Created`, contendo a instância `DocumentationPart` recém-criada na carga útil. Por exemplo:
```
{
"_links": {
"curies": {
"href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html",
"name": "documentationpart",
"templated": true
},
"self": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq"
},
"documentationpart:delete": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq"
},
"documentationpart:update": {
"href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq"
}
},
"id": "lkn4uq",
"location": {
"path": null,
"method": null,
"name": "Pet",
"statusCode": null,
"type": "MODEL"
},
"properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}"
}
```
Repita a mesma etapa para criar uma instância de DocumentationPart para qualquer uma das propriedades do modelo.
**nota**
A instância de [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de uma entidade `MODEL` não pode ser herdada por nenhum de seus recursos filho.
## Atualizar partes da documentação
Para atualizar as partes de documentação de qualquer tipo de entidade de API, envie uma solicitação PATCH em uma instância de [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) de um identificador de parte especificado para substituir o mapa de `properties` existente por um novo.
```
PATCH /restapis/4wk1k4onj3/documentation/parts/part_id HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"patchOperations" : [ {
"op" : "replace",
"path" : "RESOURCE_PATH",
"value" : "NEW_properties_VALUE_AS_JSON_STRING"
} ]
}
```
A resposta bem-sucedida retorna um código de status `200 OK` com a carga útil que contém a instância `DocumentationPart` atualizada.
Você pode atualizar várias partes de documentação em uma única solicitação `PATCH`.
## Listar partes da documentação
Para listar as partes de documentação de qualquer tipo de entidade de API, envie uma solicitação GET em uma coleção [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html).
```
GET /restapis/restapi_id/documentation/parts HTTP/1.1
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
```
A resposta bem-sucedida retorna um código de status `200 OK` com a carga útil que contém as instâncias `DocumentationPart` disponíveis.