将 OpenAPI 定义用于 API Gateway 中的 HTTP API
您可以使用 OpenAPI 3.0 定义文件来定义您的 HTTP API。然后，您可以将定义导入 API Gateway 中以创建 API。要了解有关 OpenAPI 的 API Gateway 扩展的更多信息，请参阅 适用于 API Gateway 的 OpenAPI 扩展。
导入 HTTP API
您可以通过导入 OpenAPI 3.0 定义文件来创建 HTTP API。
要从 REST API 迁移到 HTTP API，您可以将 REST API 导出为 OpenAPI 3.0 定义文件。然后，将 API 定义导入为 HTTP API。要了解有关导出 REST API 的更多信息，请参阅 从 API Gateway 导出 REST API。
注意
HTTP API 与 REST API 支持相同的Amazon变量。要了解更多信息，请参阅“Amazon用于 OpenAPI 导入的变量”。
导入验证信息
导入 API 时，API Gateway 提供三类验证信息。
- Info
-
根据 OpenAPI 规范，属性是有效的，但对于 HTTP API 不支持该属性。
例如，以下 OpenAPI 3.0 代码段生成有关导入的信息，因为 HTTP API 不支持请求验证。API Gateway 忽略
requestBody和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" } } } ... } ... } - 警告
-
根据 OpenAPI 规范，属性或结构是无效的，但它不会阻止 API 创建。您可以指定 API Gateway 是应忽略这些警告并继续创建 API，还是在出现警告时停止创建 API。
以下 OpenAPI 3.0 文档在导入时生成警告，因为 HTTP API 只支持 Lambda 代理和 HTTP 代理集成。
"x-amazon-apigateway-integration": { "type": "AWS", "httpMethod": "POST", "uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld", "payloadFormatVersion": "1.0" } - 错误
-
OpenAPI 规范无效或格式错误。API Gateway 无法从格式错误的文档创建任何资源。您必须修复错误，然后重试。
以下 API 定义会在导入时产生错误，因为 HTTP API 只支持 OpenAPI 3.0 规范。
{ "swagger": "2.0.0", "info": { "title": "My API", "description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo", "version": "1.0" } ... }在另一个示例中，虽然 OpenAPI 允许用户定义一个具有与特定操作相关的多个安全要求的 API，但 API Gateway 不支持这一点。每个操作只能有一个 IAM 授权、一个 Lambda 授权者或一个 JWT 授权者。尝试对多个安全要求进行建模会导致错误。
使用 Amazon CLI 导入 API
以下 import-api 命令将 OpenAPI 3.0 定义文件 api-definition.json 导入为 HTTP API。
例
aws apigatewayv2 import-api --body file://api-definition.json
例
您可以导入以下示例 OpenAPI 3.0 定义来创建 HTTP API。
{ "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" ] } } } }