使用 HTTP API 的 OpenAPI 定义 - Amazon API Gateway
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

使用 HTTP API 的 OpenAPI 定义

您可以使用 OpenAPI 3.0 定义文件来定义您的 HTTP API。然后,您可以将定义导入 API Gateway 中以创建 API。要了解有关 OpenAPI 的 API Gateway 扩展的更多信息,请参阅 使用基于 OpenAPI 的 API Gateway 扩展

导入 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 支持相同的 AWS 变量。要了解更多信息,请参阅“用于 OpenAPI 导入的 AWS 变量”。

导入验证信息

导入 API 时,API Gateway 提供三类验证信息。

Info

根据 OpenAPI 规范,属性是有效的,但对于 HTTP API 不支持该属性。

例如,以下 OpenAPI 3.0 代码段生成有关导入的信息,因为 HTTP API 不支持请求验证。API Gateway 忽略 requestBodyschema 字段。

"paths": { "/": { "get": { "x-amazon-apigateway-integration": { "type": "AWS_PROXY", "httpMethod": "POST", "uri": "arn:aws:lambda:us-west-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-west-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" } ... }

使用 AWS CLI 导入 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" ] } } } }