Publicar a documentação da API usando a API REST do API Gateway

Para publicar a documentação de uma API, crie, atualize ou obtenha um snapshot de documentação e depois associe esse snapshot a um estágio de API. Ao criar um snapshot de documentação, você também pode associá-lo a um estágio de API ao mesmo tempo.

Criar um snapshot de documentação e associá-lo a um estágio de API

Para criar um snapshot das partes de documentação de uma API e associá-lo a um estágio de API ao mesmo tempo, envie a seguinte solicitação POST:

POST /restapis/restapi_id/documentation/versions 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

{
    "documentationVersion" : "1.0.0",
    "stageName": "prod",
    "description" : "My API Documentation v1.0.0"
}

Se bem-sucedida, a operação retorna uma resposta 200 OK, contendo a instância recentemente DocumentationVersion criada como a carga útil.

Como alternativa, você pode criar um snapshot de documentação sem associá-lo a um estágio da API primeiro e, depois, chamar restapi:update para associar esse snapshot a um estágio da API especificado. Você também pode atualizar ou consultar um snapshot de documentação existente e depois atualizar sua associação de estágio. Mostramos as etapas nas próximas quatro seções.

Criar um snapshot de documentação

Para criar um snapshot de partes de documentação de uma API, crie um recurso DocumentationVersion e adicione-o à coleção DocumentationVersions da API:

POST /restapis/restapi_id/documentation/versions 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

{
    "documentationVersion" : "1.0.0",
    "description" : "My API Documentation v1.0.0"
}

Se bem-sucedida, a operação retorna uma resposta 200 OK, contendo a instância recentemente DocumentationVersion criada como a carga útil.

Atualizar um snapshot de documentação

Você só pode atualizar um snapshot de documentação modificando a propriedade description do recurso DocumentationVersion correspondente. O exemplo a seguir mostra como atualizar a descrição do snapshot de documentação, conforme identificado por seu identificador de versão, version, por exemplo, 1.0.0.

PATCH /restapis/restapi_id/documentation/versions/version 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": "/description",
        "value": "My API for testing purposes."
    }]
}

Se bem-sucedida, a operação retornará uma resposta 200 OK, contendo a instância DocumentationVersion atualizada como a carga útil.

Obter um snapshot de documentação

Para obter um snapshot de documentação, envie uma solicitação GET com base no recurso DocumentationVersion especificado. O exemplo a seguir mostra como obter um snapshot de documentação de um determinado identificador de versão, 1.0.0.

GET /restapis/<restapi_id>/documentation/versions/1.0.0 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

Associar um snapshot de documentação a um estágio de API

Para publicar a documentação da API, associe um snapshot de documentação a um estágio de API. Você já deve ter criado um estágio de API antes de associar a versão da documentação ao estágio.

Para associar um snapshot de documentação a um estágio de API usando a API REST do API Gateway, chame a operação stage:update para definir a versão de documentação desejada na propriedade stage.documentationVersion:

PATCH /restapis/RESTAPI_ID/stages/STAGE_NAME
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": "/documentationVersion",
        "value": "VERSION_IDENTIFIER"
    }]
}

Fazer download de um snapshot de documentação associado a um estágio

Depois que uma versão das partes da documentação é associada a um estágio, você pode exportar as partes da documentação junto com as definições de entidades de API para um arquivo externo, usando o console do API Gateway, a API REST do API Gateway, um dos SDKs ou a AWS CLI para o API Gateway. O processo é o mesmo para a exportação da API. O formato do arquivo exportado pode ser JSON ou YAML.

Usando a API REST do API Gateway, você também pode definir explicitamente o parâmetro de consulta extension=documentation,integrations,authorizers para incluir as partes de documentação da API, as integrações da API e os autorizadores em uma exportação de API. Por padrão, partes de documentação são incluídas, mas integrações e autorizadores são excluídos, quando você exporta uma API. A saída padrão de uma exportação de API é adequada para a distribuição da documentação.

Para exportar a documentação da API em um arquivo do OpenAPI JSON externo usando a API REST do API Gateway, envie a seguinte solicitação GET:

GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=documentation HTTP/1.1
Accept: application/json
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

Aqui, o objeto x-amazon-apigateway-documentation contém as partes de documentação, e as definições da entidade de API contêm as propriedades de documentação com suporte pelo OpenAPI. A saída não inclui detalhes de integração nem dos autorizadores do Lambda (anteriormente conhecidos como autorizadores personalizados). Para incluir ambos os detalhes, defina extensions=integrations,authorizers,documentation. Para incluir detalhes de integrações, mas não de autorizadores, defina extensions=integrations,documentation.

Você deve definir o cabeçalho Accept:application/json na solicitação para processar a saída do resultado em um arquivo JSON. Para produzir a saída YAML, altere o cabeçalho da solicitação para Accept:application/yaml.

Como exemplo, vamos observar uma API que expõe um método simples GET no recurso raiz (/). Essa API tem quatro entidades de API definidas em um arquivo de definição do OpenAPI, uma para cada um dos tipos API, MODEL, METHOD e RESPONSE. Uma parte de documentação foi adicionada a cada uma das entidades API, METHOD e RESPONSE. Chamando o comando de exportação de documentação anterior, obtemos a seguinte saída, com as partes de documentação listadas dentro do objeto x-amazon-apigateway-documentation como uma extensão de um arquivo padrão do OpenAPI.

OpenAPI 3.0

{
   "openapi": "3.0.0",
   "info": {
      "description": "API info description",
      "version": "2016-11-22T22:39:14Z",
      "title": "doc",
      "x-bar": "API info x-bar"
   },
   "paths": {
      "/": {
         "get": {
            "description": "Method description.",
            "responses": {
               "200": {
                  "description": "200 response",
                  "content": {
                     "application/json": {
                        "schema": {
                           "$ref": "#/components/schemas/Empty"
                        }
                     }
                  }
               }
            },
            "x-example": "x- Method example"
         },
         "x-bar": "resource x-bar"
      }
   },
   "x-amazon-apigateway-documentation": {
      "version": "1.0.0",
      "createdDate": "2016-11-22T22:41:40Z",
      "documentationParts": [
         {
            "location": {
               "type": "API"
            },
            "properties": {
               "description": "API description",
               "foo": "API foo",
               "x-bar": "API x-bar",
               "info": {
                  "description": "API info description",
                  "version": "API info version",
                  "foo": "API info foo",
                  "x-bar": "API info x-bar"
               }
            }
         },
         {
            "location": {
               "type": "METHOD",
               "method": "GET"
            },
            "properties": {
               "description": "Method description.",
               "x-example": "x- Method example",
               "foo": "Method foo",
               "info": {
                  "version": "method info version",
                  "description": "method info description",
                  "foo": "method info foo"
               }
            }
         },
         {
            "location": {
               "type": "RESOURCE"
            },
            "properties": {
               "description": "resource description",
               "foo": "resource foo",
               "x-bar": "resource x-bar",
               "info": {
                  "description": "resource info description",
                  "version": "resource info version",
                  "foo": "resource info foo",
                  "x-bar": "resource info x-bar"
               }
            }
         }
      ]
   },
   "x-bar": "API x-bar",
   "servers": [
      {
         "url": "https://rznaap68yi.execute-api.ap-southeast-1.amazonaws.com/{basePath}",
         "variables": {
            "basePath": {
              "default": "/test"
            }
         }
      }
   ],
   "components": {
      "schemas": {
         "Empty": {
            "type": "object",
            "title": "Empty Schema"
         }
      }
   }
}

OpenAPI 2.0

{
  "swagger" : "2.0",
  "info" : {
    "description" : "API info description",
    "version" : "2016-11-22T22:39:14Z",
    "title" : "doc",
    "x-bar" : "API info x-bar"
  },
  "host" : "rznaap68yi.execute-api.ap-southeast-1.amazonaws.com",
  "basePath" : "/test",
  "schemes" : [ "https" ],
  "paths" : {
    "/" : {
      "get" : {
        "description" : "Method description.",
        "produces" : [ "application/json" ],
        "responses" : {
          "200" : {
            "description" : "200 response",
            "schema" : {
              "$ref" : "#/definitions/Empty"
            }
          }
        },
        "x-example" : "x- Method example"
      },
      "x-bar" : "resource x-bar"
    }
  },
  "definitions" : {
    "Empty" : {
      "type" : "object",
      "title" : "Empty Schema"
    }
  },
  "x-amazon-apigateway-documentation" : {
    "version" : "1.0.0",
    "createdDate" : "2016-11-22T22:41:40Z",
    "documentationParts" : [ {
      "location" : {
        "type" : "API"
      },
      "properties" : {
        "description" : "API description",
        "foo" : "API foo",
        "x-bar" : "API x-bar",
        "info" : {
          "description" : "API info description",
          "version" : "API info version",
          "foo" : "API info foo",
          "x-bar" : "API info x-bar"
        }
      }
    }, {
      "location" : {
        "type" : "METHOD",
        "method" : "GET"
      },
      "properties" : {
        "description" : "Method description.",
        "x-example" : "x- Method example",
        "foo" : "Method foo",
        "info" : {
          "version" : "method info version",
          "description" : "method info description",
          "foo" : "method info foo"
        }
      }
    }, {
      "location" : {
        "type" : "RESOURCE"
      },
      "properties" : {
        "description" : "resource description",
        "foo" : "resource foo",
        "x-bar" : "resource x-bar",
        "info" : {
          "description" : "resource info description",
          "version" : "resource info version",
          "foo" : "resource info foo",
          "x-bar" : "resource info x-bar"
        }
      }
    } ]
  },
  "x-bar" : "API x-bar"
}

Para um atributo compatível com o OpenAPI definido no mapa de properties de uma parte de documentação, o API Gateway insere esse atributo na definição de entidade de API associada. Um atributo de x-something é uma extensão do OpenAPI padrão. Essa extensão é propagada na definição da entidade de API. Por exemplo, consulte o atributo x-example do método GET. Um atributo como foo não faz parte da especificação OpenAPI e não é injetado em suas definições de entidade de API associadas.

Se uma ferramenta de renderização de documentação (por exemplo, a interface do OpenAPI) analisar as definições de entidades de API para extrair atributos de documentação, nenhum dos atributos de properties não compatíveis com o OpenAPI de uma instância de DocumentationPart estará disponível para a ferramenta. No entanto, se uma ferramenta de renderização de documentação analisar o objeto x-amazon-apigateway-documentation para obter conteúdo, ou se a ferramenta chamar restapi:documentation-parts e documenationpart:by-id para recuperar partes da documentação do API Gateway, todos os atributos da documentação estarão disponíveis para a ferramenta exibir.

Para exportar a documentação com as definições de entidades de API contendo detalhes de integração para um arquivo JSON do OpenAPI, envie a seguinte solicitação GET:

GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,documentation HTTP/1.1
Accept: application/json
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

Para exportar a documentação com as definições de entidades de API contendo detalhes de integrações e autorizadores para um arquivo YAML do OpenAPI, envie a seguinte solicitação GET:

GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,authorizers,documentation HTTP/1.1
Accept: application/yaml
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

Para usar o console do API Gateway para exportar e fazer download da documentação publicada de uma API, siga as instruções em Exportar API REST usando o console do API Gateway.