Utilizzo delle definizioni OpenAPI per API HTTP in Gateway API - Amazon API Gateway
Importazione di un'API HTTP

Utilizzo delle definizioni OpenAPI per API HTTP in Gateway API

È possibile definire l'API HTTP utilizzando un file di definizione OpenAPI 3.0. Quindi è possibile importare la definizione in API Gateway per creare un'API. Per ulteriori informazioni sulle estensioni di API Gateway verso OpenAPI, consultare Estensioni OpenAPI per Gateway API.

Importazione di un'API HTTP

È possibile creare un'API HTTP importando un file di definizione OpenAPI 3.0.

Per eseguire la migrazione da un'API REST a un'API HTTP, è possibile esportare l'API REST come file di definizione OpenAPI 3.0. Quindi importare la definizione dell'API come un'API HTTP. Per ulteriori informazioni sull'esportazione di un'API REST, consultare Esportazione di un'API REST da API Gateway.

Nota

Le API HTTP supportano le stesse variabili AWS delle API REST. Per ulteriori informazioni, consulta AWS Variabili per l'importazione OpenAPI.

Informazioni di convalida dell'importazione

Quando si importa un'API, API Gateway fornisce tre categorie di informazioni di convalida.

Info

Una proprietà è valida in base alla specifica OpenAPI, ma tale proprietà non è supportata per le API HTTP.

Ad esempio, la seguente porzione di codice di OpenAPI 3.0 produce informazioni sull'importazione perché le API HTTP non supportano la convalida della richiesta. API Gateway ignora i campi 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"
        }
      }
    }
    ...
  }
  ...
}
Attenzione

Una proprietà o una struttura non è valida in base alla specifica OpenAPI, ma non blocca la creazione di API. È possibile specificare se l'API Gateway deve ignorare questi avvisi e continuare a creare l'API o interrompere la creazione dell'API n caso di presenza di avvisi.

Il seguente documento OpenAPI 3.0 produce avvisi sull'importazione perché le API HTTP supportano solo le integrazioni proxy Lambda e proxy HTTP.

"x-amazon-apigateway-integration": {
  "type": "AWS",
  "httpMethod": "POST",
  "uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
  "payloadFormatVersion": "1.0"
}
Errore

La specifica OpenAPI non è valida o è malformata. API Gateway non è in grado di creare alcuna risorsa dal documento malformato. È necessario correggere gli errori e quindi riprovare.

La seguente definizione API produce errori durante l'importazione perché le API HTTP supportano solo la specifica OpenAPI 3.0.

{
  "swagger": "2.0.0",
  "info": {
    "title": "My API",
    "description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo",
    "version": "1.0"
  }
  ...
}

Come altro esempio, mentre OpenAPI consente agli utenti di definire un'API con più requisiti di sicurezza associati a una particolare operazione, API Gateway non supporta questa operazione. Ogni operazione può avere solo un'autorizzazione IAM, un provider di autorizzazioni Lambda o un provider di autorizzazioni JWT. Il tentativo di modellare più requisiti di sicurezza genera un errore.

Importare un'API utilizzando l AWS CLI

Il comando import-api seguente importa il file di definizione OpenAPI 3.0 api-definition.json come API HTTP:

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

È possibile importare la seguente definizione OpenAPI 3.0 di esempio per creare un'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"
        ]
      }
    }
  }
}