# Documentar uma API usando o console do API Gateway
<a name="api-gateway-documenting-api-quick-start-with-console"></a>

Nesta seção, descrevemos como criar e manter partes da documentação de uma API usando o console do API Gateway. 

Um pré-requisito para criar e editar a documentação de uma API é que você já deve ter criado essa API. 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-document-api-add-document-part-for-api-entity-with-console)
+ [Documentar uma entidade `RESOURCE`](#api-gateway-document-api-add-document-part-for-resource-entity-with-console)
+ [Documentar uma entidade `METHOD`](#api-gateway-document-api-add-document-part-for-method-entity-with-console)
+ [Documentar uma entidade `QUERY_PARAMETER`](#api-gateway-document-api-add-document-part-for-request-query-entity-with-console)
+ [Documentar uma entidade `PATH_PARAMETER`](#api-gateway-document-api-add-document-part-for-path-parameter-entity-with-console)
+ [Documentar uma entidade `REQUEST_HEADER`](#api-gateway-document-api-add-document-part-for-request-header-entity-with-console)
+ [Documentar uma entidade `REQUEST_BODY`](#api-gateway-document-api-add-document-part-for-request-body-entity-with-console)
+ [Documentar uma entidade `RESPONSE`](#api-gateway-document-api-add-document-part-for-response-with-console)
+ [Documentar uma entidade `RESPONSE_HEADER`](#api-gateway-document-api-add-document-part-for-response-header-entity-with-console)
+ [Documentar uma entidade `RESPONSE_BODY`](#api-gateway-document-api-add-document-part-for-response-body-entity-with-console)
+ [Documentar uma entidade `MODEL`](#api-gateway-document-api-add-document-part-for-model-entity-with-console)
+ [Documentar uma entidade `AUTHORIZER`](#api-gateway-document-api-add-document-part-for-authorizer-entity-with-console)

## Documentar a entidade `API`
<a name="api-gateway-document-api-add-document-part-for-api-entity-with-console"></a>

Para adicionar uma nova parte da documentação da entidade `API`, faça o seguinte:

1. No painel de navegação principal, selecione **Documentação** e, depois, **Criar parte da documentação**.

1. Em **Tipo de documentação**, selecione **API**.

   Se uma parte de documentação não tiver criada para a `API`, você acessará o editor de mapa de `properties` da parte da documentação. Insira o mapa `properties` a seguir no editor de texto. 

   ```
   {
     "info": {
       "description": "Your first API Gateway API.",
       "contact": {
           "name": "John Doe",
           "email": "john.doe@api.com"
       }
     }
   }
   ```
**nota**  
 Não é necessário codificar o mapa de `properties` em uma string JSON. O console do API Gateway faz a codificação em string do objeto JSON para você. 

1. Escolha **Criar parte da documentação**.

Para adicionar uma nova parte da documentação da entidade `API` no painel **Recursos**, faça o seguinte:

1. No painel de navegação principal, selecione **Recursos**.

1. Selecione o menu **Ações de API** e escolha **Atualizar a documentação da API**.

      
![\[Editar a documentação da entidade de API no console do API Gateway\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/document-api-entity-using-new-console.png)

Para editar uma parte da documentação existente, faça o seguinte:

1. No painel **Documentação**, selecione a guia **Recursos e métodos**.

1. Selecione o nome da API e, no cartão da API, escolha **Editar**.

## Documentar uma entidade `RESOURCE`
<a name="api-gateway-document-api-add-document-part-for-resource-entity-with-console"></a>

 Para adicionar uma nova documentação de uma entidade `RESOURCE`, faça o seguinte:

1. No painel de navegação principal, selecione **Documentação** e, depois, **Criar parte da documentação**.

1. Em **Tipo de documentação**, selecione **Recurso**.

1. Em **Caminho**, insira um caminho.

1. Digite uma descrição no editor de texto; por exemplo:

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

1. Escolha **Criar parte da documentação**. É possível criar documentação para um recurso não listado.

1.  Se necessário, repita essas etapas para adicionar ou editar outra parte da documentação.

Para adicionar uma nova parte da documentação de uma entidade `RESOURCE` no painel **Recursos**, faça o seguinte:

1. No painel de navegação principal, selecione **Recursos**.

1. Selecione o recurso e escolha **Atualizar documentação**.

      
![\[Editar a documentação da entidade de recurso no console do API Gateway\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/document-resource-entity-using-new-console.png)

Para editar uma parte da documentação existente, faça o seguinte:

1. No painel **Documentação**, selecione a guia **Recursos e métodos**.

1. Selecione o recurso que contém a parte da documentação e escolha **Editar**.

## Documentar uma entidade `METHOD`
<a name="api-gateway-document-api-add-document-part-for-method-entity-with-console"></a>

 Para adicionar uma nova documentação de uma entidade `METHOD`, faça o seguinte:

1. No painel de navegação principal, selecione **Documentação** e, depois, **Criar parte da documentação**.

1. Em **Tipo de documentação**, selecione **Método**.

1. Em **Caminho**, insira um caminho.

1. Em **Método**, selecione um verbo HTTP.

1. Digite uma descrição no editor de texto; por exemplo:

   ```
   {
     "tags" : [ "pets" ],
     "summary" : "List all pets"
   }
   ```

1. Escolha **Criar parte da documentação**. É possível criar documentação para um método não listado.

1.  Se necessário, repita essas etapas para adicionar ou editar outra parte da documentação.

Para adicionar uma nova parte da documentação de uma entidade `METHOD` no painel **Recursos**, faça o seguinte:

1. No painel de navegação principal, selecione **Recursos**.

1. Selecione o método e escolha **Atualizar documentação**.

      
![\[Editar a documentação da entidade de método no console do API Gateway\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/document-method-entity-using-new-console.png)

Para editar uma parte da documentação existente, faça o seguinte:

1. No painel **Documentação**, selecione a guia **Recursos e métodos**.

1. É possível selecionar o método ou o recurso que contém o método e usar a barra de pesquisa para localizar e selecionar a parte da documentação.

1.  Escolha **Editar**.

## Documentar uma entidade `QUERY_PARAMETER`
<a name="api-gateway-document-api-add-document-part-for-request-query-entity-with-console"></a>

 Para adicionar uma nova documentação de uma entidade `QUERY_PARAMETER`, faça o seguinte:

1. No painel de navegação principal, selecione **Documentação** e, depois, **Criar parte da documentação**.

1. Em **Tipo de documentação**, selecione **Parâmetro de consulta**.

1. Em **Caminho**, insira um caminho.

1. Em **Método**, selecione um verbo HTTP.

1. **Nome**, insira um nome.

1. Digite uma descrição no editor de texto.

1. Escolha **Criar parte da documentação**. É possível criar documentação para um parâmetro de consulta não listado.

1.  Se necessário, repita essas etapas para adicionar ou editar outra parte da documentação.

Para editar uma parte da documentação existente, faça o seguinte:

1. No painel **Documentação**, selecione a guia **Recursos e métodos**.

1. É possível selecionar o parâmetro de consulta ou o recurso que contém o parâmetro de consulta e usar a barra de pesquisa para localizar e selecionar a parte da documentação.

1. Escolha **Editar**.

## Documentar uma entidade `PATH_PARAMETER`
<a name="api-gateway-document-api-add-document-part-for-path-parameter-entity-with-console"></a>

 Para adicionar uma nova documentação de uma entidade `PATH_PARAMETER`, faça o seguinte:

1. No painel de navegação principal, selecione **Documentação** e, depois, **Criar parte da documentação**.

1. Em **Tipo de documentação**, selecione **Parâmetro de caminho**.

1. Em **Caminho**, insira um caminho.

1. Em **Método**, selecione um verbo HTTP.

1. **Nome**, insira um nome.

1. Digite uma descrição no editor de texto.

1. Escolha **Criar parte da documentação**. É possível criar documentação para um parâmetro de caminho não listado.

1.  Se necessário, repita essas etapas para adicionar ou editar outra parte da documentação.

Para editar uma parte da documentação existente, faça o seguinte:

1. No painel **Documentação**, selecione a guia **Recursos e métodos**.

1. É possível selecionar o parâmetro de caminho ou o recurso que contém o parâmetro de caminho e usar a barra de pesquisa para localizar e selecionar a parte da documentação.

1. Escolha **Editar**.

## Documentar uma entidade `REQUEST_HEADER`
<a name="api-gateway-document-api-add-document-part-for-request-header-entity-with-console"></a>

 Para adicionar uma nova documentação de uma entidade `REQUEST_HEADER`, faça o seguinte:

1. No painel de navegação principal, selecione **Documentação** e, depois, **Criar parte da documentação**.

1. Em **Tipo de documentação**, selecione **Cabeçalho da solicitação**.

1. Em **Caminho**, insira um caminho para o cabeçalho da solicitação.

1. Em **Método**, selecione um verbo HTTP.

1. **Nome**, insira um nome.

1. Digite uma descrição no editor de texto.

1. Escolha **Criar parte da documentação**. É possível criar documentação para um cabeçalho da solicitação não listado.

1.  Se necessário, repita essas etapas para adicionar ou editar outra parte da documentação.

Para editar uma parte da documentação existente, faça o seguinte:

1. No painel **Documentação**, selecione a guia **Recursos e métodos**.

1. É possível selecionar o cabeçalho da solicitação ou o recurso que contém o cabeçalho e usar a barra de pesquisa para localizar e selecionar a parte da documentação.

1. Escolha **Editar**.

## Documentar uma entidade `REQUEST_BODY`
<a name="api-gateway-document-api-add-document-part-for-request-body-entity-with-console"></a>

 Para adicionar uma nova documentação de uma entidade `REQUEST_BODY`, faça o seguinte:

1. No painel de navegação principal, selecione **Documentação** e, depois, **Criar parte da documentação**.

1. Em **Tipo de documentação**, selecione **Corpo da solicitação**.

1. Em **Caminho**, insira um caminho para o corpo da solicitação.

1. Em **Método**, selecione um verbo HTTP.

1. Digite uma descrição no editor de texto.

1. Escolha **Criar parte da documentação**. É possível criar documentação para um corpo da solicitação não listado.

1.  Se necessário, repita essas etapas para adicionar ou editar outra parte da documentação.

Para editar uma parte da documentação existente, faça o seguinte:

1. No painel **Documentação**, selecione a guia **Recursos e métodos**.

1. É possível selecionar o corpo da solicitação ou o recurso que contém o corpo e usar a barra de pesquisa para localizar e selecionar a parte da documentação.

1. Escolha **Editar**.

## Documentar uma entidade `RESPONSE`
<a name="api-gateway-document-api-add-document-part-for-response-with-console"></a>

 Para adicionar uma nova documentação de uma entidade `RESPONSE`, faça o seguinte:

1. No painel de navegação principal, selecione **Documentação** e, depois, **Criar parte da documentação**.

1. Em **Tipo de documentação**, selecione **Resposta (código de status)**.

1. Em **Caminho**, insira um caminho para a resposta.

1. Em **Método**, selecione um verbo HTTP.

1. Em **Código de status**, insira um código de status HTTP.

1. Digite uma descrição no editor de texto.

1. Escolha **Criar parte da documentação**. É possível criar documentação para um status de resposta não listado.

1.  Se necessário, repita essas etapas para adicionar ou editar outra parte da documentação.

Para editar uma parte da documentação existente, faça o seguinte:

1. No painel **Documentação**, selecione a guia **Recursos e métodos**.

1. É possível selecionar o código de status da resposta ou o recurso que contém o código e usar a barra de pesquisa para localizar e selecionar a parte da documentação.

1. Escolha **Editar**.

## Documentar uma entidade `RESPONSE_HEADER`
<a name="api-gateway-document-api-add-document-part-for-response-header-entity-with-console"></a>

 Para adicionar uma nova documentação de uma entidade `RESPONSE_HEADER`, faça o seguinte:

1. No painel de navegação principal, selecione **Documentação** e, depois, **Criar parte da documentação**.

1. Em **Tipo de documentação**, selecione **Cabeçalho da resposta**.

1. Em **Caminho**, insira um caminho para o cabeçalho da resposta.

1. Em **Método**, selecione um verbo HTTP.

1. Em **Código de status**, insira um código de status HTTP.

1. Digite uma descrição no editor de texto.

1. Escolha **Criar parte da documentação**. É possível criar documentação para um cabeçalho da resposta não listado.

1.  Se necessário, repita essas etapas para adicionar ou editar outra parte da documentação.

Para editar uma parte da documentação existente, faça o seguinte:

1. No painel **Documentação**, selecione a guia **Recursos e métodos**.

1. É possível selecionar o cabeçalho da resposta ou o recurso que contém o cabeçalho e usar a barra de pesquisa para localizar e selecionar a parte da documentação.

1. Escolha **Editar**.

## Documentar uma entidade `RESPONSE_BODY`
<a name="api-gateway-document-api-add-document-part-for-response-body-entity-with-console"></a>

 Para adicionar uma nova documentação de uma entidade `RESPONSE_BODY`, faça o seguinte:

1. No painel de navegação principal, selecione **Documentação** e, depois, **Criar parte da documentação**.

1. Em **Tipo de documentação**, selecione **Corpo da resposta**.

1. Em **Caminho**, insira um caminho para o corpo da resposta.

1. Em **Método**, selecione um verbo HTTP.

1. Em **Código de status**, insira um código de status HTTP.

1. Digite uma descrição no editor de texto.

1. Escolha **Criar parte da documentação**. É possível criar documentação para um corpo da resposta não listado.

1.  Se necessário, repita essas etapas para adicionar ou editar outra parte da documentação.

Para editar uma parte da documentação existente, faça o seguinte:

1. No painel **Documentação**, selecione a guia **Recursos e métodos**.

1. É possível selecionar o corpo da resposta ou o recurso que contém o corpo e usar a barra de pesquisa para localizar e selecionar a parte da documentação.

1. Escolha **Editar**.

## Documentar uma entidade `MODEL`
<a name="api-gateway-document-api-add-document-part-for-model-entity-with-console"></a>

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 uma nova documentação de uma entidade `MODEL`, faça o seguinte:

1. No painel de navegação principal, selecione **Documentação** e, depois, **Criar parte da documentação**.

1. Em **Tipo de documentação**, selecione **Modelo**.

1. Em **Nome**, insira um nome para o modelo.

1. Digite uma descrição no editor de texto.

1. Escolha **Criar parte da documentação**. É possível criar documentação para modelos não listados.

1.  Se necessário, repita essas etapas para editar ou adicionar uma parte de documentação a outros modelos.

Para adicionar uma nova parte da documentação de uma entidade `MODEL` no painel **Modelos**, faça o seguinte:

1. No painel de navegação principal, selecione **Modelos**.

1. Selecione o modelo e escolha **Atualizar documentação**.

      
![\[Editar a documentação da entidade de modelo no console do API Gateway\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/document-model-entity-using-new-console.png)

Para editar uma parte da documentação existente, faça o seguinte:

1. No painel **Documentação**, selecione a guia **Modelos**.

1. Use a barra de pesquisa ou selecione o modelo e, depois, escolha **Editar**.

## Documentar uma entidade `AUTHORIZER`
<a name="api-gateway-document-api-add-document-part-for-authorizer-entity-with-console"></a>

 Para adicionar uma nova documentação de uma entidade `AUTHORIZER`, faça o seguinte:

1. No painel de navegação principal, selecione **Documentação** e, depois, **Criar parte da documentação**.

1. Em **Tipo de documentação**, selecione **Autorizador**.

1. Em **Nome**, insira o nome do autorizador.

1. Digite uma descrição no editor de texto. Especifique um valor para o campo `location` válido para o autorizador.

1. Escolha **Criar parte da documentação**. É possível criar documentação para autorizadores não listados.

1.  Se necessário, repita essas etapas para editar ou adicionar uma parte de documentação a outros autorizadores.

Para editar uma parte da documentação existente, faça o seguinte:

1. No painel **Documentação**, selecione a guia **Autorizadores**.

1. Use a barra de pesquisa ou selecione o autorizador e, depois, escolha **Editar**.