# Uso de definiciones de OpenAPI para las API HTTP en API Gateway Para definir su API HTTP, puede utilizar un archivo de definición de OpenAPI 3.0. A continuación, puede importar la definición a API Gateway para crear una API. Para obtener más información sobre las extensiones de API Gateway para OpenAPI, consulte [Extensiones de OpenAPI para API Gateway](api-gateway-swagger-extensions.md). ## Importación de una API HTTP Para crear una API HTTP, puede importar un archivo de definición de OpenAPI 3.0. Para migrar desde una API de REST a una API HTTP, puede exportar la API de REST como un archivo de definición de OpenAPI 3.0. A continuación, importe la definición de la API como una API HTTP. Para obtener más información acerca de cómo exportar una API de REST, consulte [Exportación de una API REST desde API Gateway](api-gateway-export-api.md). **nota** Las API HTTP admiten las mismas variables de AWS que las API REST. Para obtener más información, consulte [Variables de AWS para la importación de OpenAPI](import-api-aws-variables.md). ### Importar información de validación Al importar una API, API Gateway proporciona tres categorías de información de validación. **Información** Una propiedad es válida de acuerdo con la especificación de OpenAPI, pero dicha propiedad no es compatible con las API HTTP. Por ejemplo, el siguiente fragmento de OpenAPI 3.0 genera información en la importación porque las API HTTP no son compatibles con la validación de solicitudes. API Gateway ignora los campos `requestBody` y `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" } } } ... } ... } ``` **Advertencia** Una propiedad o estructura no es válida de acuerdo con la especificación de OpenAPI, pero no bloquea la creación de API. Puede especificar si API Gateway debe hacer caso omiso de estas advertencias y seguir creando la API o dejar de crear la API según las advertencias. El siguiente documento de OpenAPI 3.0 genera advertencias en la importación porque las API HTTP solo son compatibles con integraciones de proxy de Lambda y proxy de HTTP. ``` "x-amazon-apigateway-integration": { "type": "AWS", "httpMethod": "POST", "uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld", "payloadFormatVersion": "1.0" } ``` **Error** La especificación OpenAPI no es válida o es incorrecta. API Gateway no puede crear ningún recurso a partir del documento con formato incorrecto. Debe corregir los errores y, a continuación, intentarlo de nuevo. La siguiente definición de API genera errores en la importación porque las API HTTP solo son compatibles con la especificación de OpenAPI 3.0. ``` { "swagger": "2.0.0", "info": { "title": "My API", "description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo", "version": "1.0" } ... } ``` Como otro ejemplo, mientras que OpenAPI permite a los usuarios definir una API con varios requisitos de seguridad asociados a una operación en particular, API Gateway no admite esto. Cada operación solo puede tener una autorización de IAM, un autorizador de Lambda o un autorizador JWT. Cuando se intenta modelar varios requisitos de seguridad, se produce un error. ### Importación de una API con la AWS CLI El siguiente comando [import-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/import-api.html) permite importar el archivo de definición de OpenAPI 3.0 `api-definition.json` como una API HTTP. **Example** ``` aws apigatewayv2 import-api --body file://api-definition.json ``` **Example** Puede importar el siguiente ejemplo de definición de OpenAPI 3.0 para crear una 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" ] } } } } ``` # Exportación de API HTTP desde API Gateway Después de crear una API HTTP, puede exportar una definición de OpenAPI 3.0 de su API desde API Gateway. Puede elegir una etapa que exportar o exportar la configuración más reciente de su API. También puede importar una definición de API exportada a API Gateway para crear otra API idéntica. Para obtener más información sobre la importación de definiciones de API, consulte [Importación de una API HTTP](http-api-open-api.md#http-api-import). ## Exportación de la definición de OpenAPI 3.0 de una etapa mediante AWS CLI El siguiente comando [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) permite exportar una definición de OpenAPI de una etapa de API denominada `prod` a un archivo YAML denominado `stage-definition.yaml`. El archivo de definición exportado incluye [extensiones de API Gateway](api-gateway-swagger-extensions.md) de forma predeterminada. ``` aws apigatewayv2 export-api \ --api-id api-id \ --output-type YAML \ --specification OAS30 \ --stage-name prod \ stage-definition.yaml ``` ## Exportación de una definición de OpenAPI 3.0 de los últimos cambios de la API mediante AWS CLI El siguiente comando [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) permite exportar la definición de OpenAPI de una API HTTP a un archivo JSON denominado `latest-api-definition.json`. Dado que el comando no especifica una etapa, API Gateway exporta la configuración más reciente de la API, con independencia de si se ha implementado o no en una etapa. El archivo de definición exportado no incluye [extensiones de 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 obtener más información, consulte [ExportAPI](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-exports-specification.html#apis-apiid-exports-specification-http-methods) en la *Referencia de la API de Amazon API Gateway Versión 2*. ## Exportación de una definición de OpenAPI 3.0 mediante la consola de API Gateway El procedimiento siguiente describe cómo exportar una definición de OpenAPI de una API HTTP. **Para exportar una definición de OpenAPI 3.0 con la consola de API Gateway** 1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Elija una API HTTP. 1. En el panel de navegación principal, en **Desarrollar**, elija **Exportar**. 1. Seleccione una de las siguientes opciones para exportar la API: ![\[Opciones de exportación para las API HTTP.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/export-http-api.png) 1. En **Origen**, seleccione un origen para la definición de OpenAPI 3.0. Puede elegir una etapa que exportar o exportar la configuración más reciente de la API. 1. Active **Incluir extensiones de API Gateway** para incluir las [extensiones de API Gateway](api-gateway-swagger-extensions.md). 1. En **Formato de salida**, seleccione un formato de salida. 1. Elija **Descargar**.