Uso de definiciones de OpenAPI para las API de 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.

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.

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.

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.

Importar una API con la AWS CLI

El siguiente comando importa el archivo de definición de OpenAPI 3.0 api-definition.json como una API HTTP.

aws apigatewayv2 import-api --body file://api-definition.json

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"
        ]
      }
    }
  }
}