Exportar uma API REST do API Gateway - Amazon API Gateway

Exportar uma API REST do API Gateway

Depois de criar e configurar uma API REST no API Gateway, usando o console do API Gateway ou de outra forma, você pode exportá-la para um arquivo OpenAPI usando a API de exportação do API Gateway, que faz parte do Amazon API Gateway Control Service. Para usar a API de exportação do API Gateway, você precisa assinar suas solicitações de API. Para ter mais informações sobre como assinar solicitações, consulte Assinar solicitações de API no Guia do usuário do IAM. Existem opções para incluir as extensões de integração do API Gateway, bem como as extensões do Postman, no arquivo de definição do OpenAPI exportado.

nota

Ao exportar a API usando a AWS CLI, inclua o parâmetro de extensões, conforme mostrado no exemplo a seguir, para garantir que a extensão x-amazon-apigateway-request-validator seja incluída:

aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json

Não será possível exportar uma API se suas cargas não forem do tipo application/json. Se você tentar, receberá uma resposta de erro indicando que os modelos de corpo JSON não foram encontrados.

Solicitar a exportação de uma API REST

Com o recurso Export API, você exporta uma API REST existente ao enviar uma solicitação GET, especificando a API a ser exportada como parte de caminhos de URL. A URL da solicitação tem o seguinte formato:

OpenAPI 3.0
https://<host>/restapis/<restapi_id>/stages/<stage_name>/exports/oas30
OpenAPI 2.0
https://<host>/restapis/<restapi_id>/stages/<stage_name>/exports/swagger

Você pode acrescentar a string de consulta extensions para especificar se deseja incluir extensões do API Gateway (com o valor integration) ou extensões do Postman (com o valor postman).

Além disso, é possível definir o cabeçalho Accept como application/json ou application/yaml para receber a saída da definição de API no formato JSON ou YAML, respectivamente.

Para obter mais informações sobre como enviar solicitações GET usando a API Export do API Gateway, consulte GetExport.

nota

Se você definir modelos na sua API, eles deverão ser destinados ao tipo de conteúdo “application/json” para que o API Gateway exporte o modelo. Caso contrário, o API Gateway lançará uma exceção com a mensagem de erro de que apenas modelos de corpo não JSON foram encontrados.

Os modelos devem conter propriedades ou serem definidos como um determinado tipo de JSONSchema.

Fazer download da definição da API REST do OpenAPI em JSON

Para exportar e fazer download de uma API REST em definições do OpenAPI no formato JSON:

OpenAPI 3.0
GET /restapis/<restapi_id>/stages/<stage_name>/exports/oas30 Host: apigateway.<region>.amazonaws.com Accept: application/json
OpenAPI 2.0
GET /restapis/<restapi_id>/stages/<stage_name>/exports/swagger Host: apigateway.<region>.amazonaws.com Accept: application/json

Aqui, <region> poderia ser, por exemplo, us-east-1. Para conhecer todas as regiões onde o API Gateway está disponível, consulte Regiões e endpoints.

Fazer download da definição da API REST do OpenAPI em YAML

Para exportar e fazer download de uma API REST em definições do OpenAPI no formato YAML:

OpenAPI 3.0
GET /restapis/<restapi_id>/stages/<stage_name>/exports/oas30 Host: apigateway.<region>.amazonaws.com Accept: application/yaml
OpenAPI 2.0
GET /restapis/<restapi_id>/stages/<stage_name>/exports/swagger Host: apigateway.<region>.amazonaws.com Accept: application/yaml

Fazer download da definição da API REST do OpenAPI com extensões Postman em JSON

Para exportar e fazer download de uma API REST em definições do OpenAPI com Postman no formato JSON:

OpenAPI 3.0
GET /restapis/<restapi_id>/stages/<stage_name>/exports/oas30?extensions=postman Host: apigateway.<region>.amazonaws.com Accept: application/json
OpenAPI 2.0
GET /restapis/<restapi_id>/stages/<stage_name>/exports/swagger?extensions=postman Host: apigateway.<region>.amazonaws.com Accept: application/json

Fazer download da definição da API REST do OpenAPI com integração ao API Gateway em YAML

Para exportar e fazer download de uma API REST em definições do OpenAPI com integração ao API Gateway no formato YAML:

OpenAPI 3.0
GET /restapis/<restapi_id>/stages/<stage_name>/exports/oas30?extensions=integrations Host: apigateway.<region>.amazonaws.com Accept: application/yaml
OpenAPI 2.0
GET /restapis/<restapi_id>/stages/<stage_name>/exports/swagger?extensions=integrations Host: apigateway.<region>.amazonaws.com Accept: application/yaml

Exportar API REST usando o console do API Gateway

Depois de implantar sua API REST em um estágio, você pode prosseguir e exportar essa API no estágio para um arquivo do OpenAPI usando o console do API Gateway.

No painel Estágios no console do API Gateway, escolha Estágios, Exportar.

Exportar API REST usando o console do API Gateway

Especifique Tipo de especificação da API, Formato e Extensões para baixar a definição do OpenAPI da sua API.