# Usar definições do OpenAPI para APIs HTTP no API Gateway É possível definir a API HTTP usando um arquivo de definição de OpenAPI 3.0. Depois, é possível importar a definição no API Gateway para criar uma API. Para saber mais sobre as extensões do API Gateway para OpenAPI, consulte [Extensões OpenAPI para o API Gateway](api-gateway-swagger-extensions.md). ## Importar uma API HTTP É possível criar uma API HTTP importando um arquivo de definição do OpenAPI 3.0. Para realizar a migração de uma API REST para uma API HTTP, é possível exportar sua API REST como um arquivo de definição do OpenAPI 3.0. Depois, importe a definição de API como uma API HTTP. Para saber mais sobre como exportar uma API REST, consulte [Exportar uma API REST do API Gateway](api-gateway-export-api.md). **nota** As APIs HTTP são compatíveis com as mesmas variáveis da AWS que as APIs REST. Para saber mais, consulte [Variáveis da AWS para importação de OpenAPI](import-api-aws-variables.md). ### Importar informações de validação À medida que você importa uma API, o API Gateway fornece três categorias de informações de validação. **Informações** Uma propriedade é válida de acordo com a especificação do OpenAPI, mas essa propriedade não é compatível com APIs HTTP. Por exemplo, o snippet do OpenAPI 3.0 a seguir produz informações sobre importação porque APIs HTTP não são compatíveis com a validação de solicitação. O API Gateway ignora os campos `requestBody` e `schema`. ``` "paths": { "/": { "get": { "x-amazon-apigateway-integration": { "type": "AWS_PROXY", "httpMethod": "POST", "uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld", "payloadFormatVersion": "1.0" }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Body" } } } } } } ... }, "components": { "schemas": { "Body": { "type": "object", "properties": { "key": { "type": "string" } } } ... } ... } ``` **Aviso** Uma propriedade ou estrutura é inválida de acordo com a especificação OpenAPI, mas não bloqueia a criação de API.çç É possível especificar se o API Gateway deve ignorar esses avisos e continuar criando a API ou parar de criar a API em avisos. O documento do OpenAPI 3.0 a seguir produz avisos na importação porque APIs HTTP são compatíveis apenas com integrações de proxy do Lambda e HTTP. ``` "x-amazon-apigateway-integration": { "type": "AWS", "httpMethod": "POST", "uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld", "payloadFormatVersion": "1.0" } ``` **Erro** A especificação do OpenAPI é inválida ou malformada. O API Gateway não pode criar recursos a partir do documento malformado. Você precisa corrigir os erros e, em seguida, tentar novamente. A definição de API a seguir produz erros na importação porque as APIs HTTP são compatíveis apenas com a especificação do OpenAPI 3.0. ``` { "swagger": "2.0.0", "info": { "title": "My API", "description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo", "version": "1.0" } ... } ``` Como outro exemplo, enquanto o OpenAPI permite que os usuários definam uma API com vários requisitos de segurança anexados a uma determinada operação, o API Gateway não oferece suporte a isso. Cada operação pode ter apenas uma autorização do IAM, um autorizador do Lambda ou um autorizador JWT. A tentativa de modelar vários requisitos de segurança resulta em um erro. ### Importar uma API usando a AWS CLI O comando [import-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/import-api.html) indicado abaixo importa o arquivo de definição `api-definition.json` do OpenAPI 3.0 como uma API HTTP: **Example** ``` aws apigatewayv2 import-api --body file://api-definition.json ``` **Example** É possível importar a definição demonstrativa do OpenAPI 3.0 a seguir para criar uma API HTTP. ``` { "openapi": "3.0.1", "info": { "title": "Example Pet Store", "description": "A Pet Store API.", "version": "1.0" }, "paths": { "/pets": { "get": { "operationId": "GET HTTP", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pets" } } } } }, "x-amazon-apigateway-integration": { "type": "HTTP_PROXY", "httpMethod": "GET", "uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets", "payloadFormatVersion": 1.0 } }, "post": { "operationId": "Create Pet", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPet" } } }, "required": true }, "responses": { "200": { "description": "200 response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPetResponse" } } } } }, "x-amazon-apigateway-integration": { "type": "HTTP_PROXY", "httpMethod": "POST", "uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets", "payloadFormatVersion": 1.0 } } }, "/pets/{petId}": { "get": { "operationId": "Get Pet", "parameters": [ { "name": "petId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "headers": { "Access-Control-Allow-Origin": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } } }, "x-amazon-apigateway-integration": { "type": "HTTP_PROXY", "httpMethod": "GET", "uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets/{petId}", "payloadFormatVersion": 1.0 } } } }, "x-amazon-apigateway-cors": { "allowOrigins": [ "*" ], "allowMethods": [ "GET", "OPTIONS", "POST" ], "allowHeaders": [ "x-amzm-header", "x-apigateway-header", "x-api-key", "authorization", "x-amz-date", "content-type" ] }, "components": { "schemas": { "Pets": { "type": "array", "items": { "$ref": "#/components/schemas/Pet" } }, "Empty": { "type": "object" }, "NewPetResponse": { "type": "object", "properties": { "pet": { "$ref": "#/components/schemas/Pet" }, "message": { "type": "string" } } }, "Pet": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "price": { "type": "number" } } }, "NewPet": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/PetType" }, "price": { "type": "number" } } }, "PetType": { "type": "string", "enum": [ "dog", "cat", "fish", "bird", "gecko" ] } } } } ``` # Exportar APIs HTTP do API Gateway Depois de criar uma API HTTP, é possível exportar uma definição do OpenAPI 3.0 da API a partir do API Gateway. Você pode escolher um estágio para exportar ou exportar a configuração mais recente da API. Também é possível importar uma definição de API exportada para o API Gateway para a criação de outra API idêntica. Para saber mais sobre a importação de definições de API, consulte [Importar uma API HTTP](http-api-open-api.md#http-api-import). ## Exportar uma definição do OpenAPI 3.0 de um estágio usando a CLI da AWS O comando [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) a seguir exporta uma definição do OpenAPI de um estágio de API chamado `prod` para um arquivo YAML denominado `stage-definition.yaml`. O arquivo de definição exportado inclui [extensões do API Gateway](api-gateway-swagger-extensions.md) por padrão. ``` aws apigatewayv2 export-api \ --api-id api-id \ --output-type YAML \ --specification OAS30 \ --stage-name prod \ stage-definition.yaml ``` ## Exporte uma definição do OpenAPI 3.0 das alterações mais recentes da API usando a CLI da AWS O comando [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) a seguir exporta uma definição do OpenAPI de uma API HTTP para um arquivo JSON denominado `latest-api-definition.json`. Como o comando não especifica um estágio, o API Gateway exporta a configuração mais recente da API, quer ela tenha sido implantada em um estágio ou não. O arquivo de definição exportado não inclui [extensões do API Gateway](api-gateway-swagger-extensions.md). ``` aws apigatewayv2 export-api \ --api-id api-id \ --output-type JSON \ --specification OAS30 \ --no-include-extensions \ latest-api-definition.json ``` Para obter mais informações, consulte [ExportAPI](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-exports-specification.html#apis-apiid-exports-specification-http-methods) na *Referência de API do Amazon API Gateway versão 2*. ## Exportar uma definição do OpenAPI 3.0 usando o console do API Gateway O procedimento a seguir mostra como exportar uma definição do OpenAPI de uma API HTTP. **Como exportar uma definição do OpenAPI 3.0 usando o console do API Gateway** 1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Selecione uma API HTTP. 1. No painel de navegação principal, em **Desenvolver**, escolha **Exportar**. 1. Selecione uma das seguintes opções para exportar a API: ![\[Opções de exportação para APIs HTTP.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/export-http-api.png) 1. Em **Origem**, selecione uma origem para a definição do OpenAPI 3.0. Você pode escolher um estágio para exportar ou exportar a configuração mais recente da API. 1. Ative a opção **Incluir extensões do API Gateway** para incluir [extensões do API Gateway](api-gateway-swagger-extensions.md). 1. Em **Formato de saída**, selecione um formato de saída. 1. Escolha **Baixar**.