Documentar uma API usando o console do API Gateway

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 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.

Documentar a entidade API

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.

2. 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": "[e-mail]"
       }
     }
   }

   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ê.

3. 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.

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

   

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

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

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

Documentar uma entidade RESOURCE

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.

2. Em Tipo de documentação, selecione Recurso.

3. Em Caminho, insira um caminho.

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

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

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

6. 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.

2. Selecione o recurso e escolha Atualizar 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.

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

Documentar uma entidade METHOD

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.

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

3. Em Caminho, insira um caminho.

4. Em Método, selecione um verbo HTTP.

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

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

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

7. 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.

2. Selecione o método e escolha Atualizar 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.

2. É 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.

3. Escolha Editar.

Documentar uma entidade QUERY_PARAMETER

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.

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

3. Em Caminho, insira um caminho.

4. Em Método, selecione um verbo HTTP.

5. Em Nome, insira um nome.

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

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

8. 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.

2. É 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.

3. Escolha Editar.

Documentar uma entidade PATH_PARAMETER

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.

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

3. Em Caminho, insira um caminho.

4. Em Método, selecione um verbo HTTP.

5. Em Nome, insira um nome.

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

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

8. 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.

2. É 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.

3. Escolha Editar.

Documentar uma entidade REQUEST_HEADER

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.

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

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

4. Em Método, selecione um verbo HTTP.

5. Em Nome, insira um nome.

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

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

8. 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.

2. É 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.

3. Escolha Editar.

Documentar uma entidade REQUEST_BODY

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.

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

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

4. Em Método, selecione um verbo HTTP.

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

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

7. 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.

2. É 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.

3. Escolha Editar.

Documentar uma entidade RESPONSE

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.

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

3. Em Caminho, insira um caminho para a resposta.

4. Em Método, selecione um verbo HTTP.

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

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

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

8. 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.

2. É 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.

3. Escolha Editar.

Documentar uma entidade RESPONSE_HEADER

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.

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

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

4. Em Método, selecione um verbo HTTP.

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

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

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

8. 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.

2. É 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.

3. Escolha Editar.

Documentar uma entidade RESPONSE_BODY

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.

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

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

4. Em Método, selecione um verbo HTTP.

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

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

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

8. 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.

2. É 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.

3. Escolha Editar.

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 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.

2. Em Tipo de documentação, selecione Modelo.

3. Em Nome, insira um nome para o modelo.

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

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

6. 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.

2. Selecione o modelo e escolha Atualizar documentação.

   

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

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

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

Documentar uma entidade AUTHORIZER

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.

2. Em Tipo de documentação, selecione Autorizador.

3. Em Nome, insira o nome do autorizador.

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

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

6. 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.

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