# REST API OpenAPI 是用于描述REST API的广泛使用标准。Gateway支持通过OpenAPI 3.0与 Swagger 2.0规范来定义 API Targets。 OpenAPI Targets使Gateway对接后端REST服务，该后端接口由导入的OpenAPI规范进行描述。Gateway将传入的MCP请求转换为这些API的HTTP请求。 #### 关键注意事项和限制 在使用 OpenAPI targets时，请注意以下要求和限制： - 仅支持OpenAPI 3.0和Swagger2.0规范的OpenAPI。 - OpenAPI 文件必须没有语义错误。 - servers属性： 仅能定义一个包含实际端点的有效 URL，仅支持静态 URL，例如：https://api.example.com/v1，且安全限制必须使用 HTTPS 协议，禁止配置以下 IP 网段： - 127.0.0.0/8 - 169.254.0.0/16 - 0.0.0.0/8 - 255.255.255.255/32 - ::/128 - ::1/128 - fe80::/10 ``` { "servers": [ { "url": "https://api.example.com/v1" } ] } ``` - method：必须是合法的 HTTP 方法（GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS）。 - 所有 operations 中必须包含唯一的 operationId，要满足长度限制，operationId 会被用作工具名称。 - $ref 引用完整性：使用 $ref 引用 #/components/schemas/ 或 #/components/requestBodies/ 时，components 必须存在。 - 在 paths 对象里，具体的路由（比如 /pet）不能直接用$ref引用来代替，必须是 Path Item 对象（包含 get、post、put 等方法定义）。 #### OpenAPI功能支持 | 功能支持 | 支持功能 | 不支持功能 | |:---|:---|:---| | 参数定义 | 支持schema定义 | 不支持content定义 | | path参数 | - 支持String和Number - 支持简单的路径参数定义（示例：/users/{userId}） - path中{userId}必须有path参数定义 | - 不支持Object/Array/Bool/Null - 不支持复杂的路径参数序列化器（示例：/users/{;id\*}） | | header参数 | - 仅支持String - 只有schema定义的header参数才会被传递 | - 不支持Object/Array/Bool/Null/Number - 不支持自定义header：content-length、content-type、transfer-encoding、host | | query参数 | - 支持String/Number/Bool/Null/Array - Array内支持String/Number/Bool/Null，Array必须使用explode=True | 不支持Object | | cookie参数 | - | 不支持 | | 请求体 | - 支持application/json格式 - 请求体定义application/json下必须使用schema-ref引用 | 不支持application/xml等格式 | | 响应体 | - | 不支持 | #### OpenAPI 模式规范 - 在配置 OpenAPI targets时，有关 OpenAPI 规范格式的信息，请参见 [OpenAPI Specification](https://spec.openapis.org/)。 - 支持的OpenAPI规范示例 - openapi 3.0 ``` { "openapi": "3.0.4", "info": { "title": "Pet Store API", "version": "1.0.0", "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification." }, "servers": [ { "url": "https://api.example.com/v1" } ], "paths": { "/pet": { "post": { "tags": [ "pet" ], "summary": "Add a new pet to the store.", "description": "Add a new pet to the store.", "operationId": "addPet", "requestBody": { "$ref": "#/components/requestBodies/Pet" }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } } } } }, "/pet/{petId}": { "get": { "summary": "Find pet by ID.", "description": "Returns a single pet.", "operationId": "getPetById", "parameters": [ { "name": "petId", "in": "path", "description": "ID of pet to return", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } } } }, "put": { "summary": "Update an existing pet.", "description": "Update an existing pet by Id.", "operationId": "updatePet", "parameters": [ { "name": "petId", "in": "path", "description": "Pet id to Update", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "description": "Update an existent pet in the store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } } } }, "delete": { "summary": "Deletes a pet.", "description": "Delete a pet.", "operationId": "deletePet", "parameters": [ { "name": "petId", "in": "path", "description": "Pet id to delete", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Pet deleted" } } } } }, "components": { "schemas": { "Pet": { "required": [ "name" ], "type": "object", "properties": { "id": { "type": "integer", "format": "int64", "example": 10 }, "name": { "type": "string", "example": "doggie" }, "status": { "type": "string", "description": "pet status in the store", "enum": [ "available", "pending", "sold" ] } } } }, "requestBodies": { "Pet": { "description": "Pet object that needs to be added to the store", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } } } } } } ``` - swagger 2.0 ``` { "swagger": "2.0", "info": { "title": "Pet Store API", "version": "1.0.0", "description": "This is a sample Pet Store Server based on the Swagger 2.0 specification." }, "host": "api.example.com", "basePath": "/v1", "schemes": ["https"], "paths": { "/pet": { "post": { "tags": ["pet"], "summary": "Add a new pet to the store.", "description": "Add a new pet to the store.", "operationId": "addPet", "consumes": ["application/json"], "parameters": [ { "name": "body", "in": "body", "description": "Pet object that needs to be added to the store", "required": true, "schema": { "$ref": "#/definitions/Pet" } } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/Pet" } } } } }, "/pet/{petId}": { "get": { "summary": "Find pet by ID.", "description": "Returns a single pet.", "operationId": "getPetById", "parameters": [ { "name": "petId", "in": "path", "description": "ID of pet to return", "required": true, "type": "integer", "format": "int64" } ], "responses": { "200": { "description": "successful operation", "schema": { "$ref": "#/definitions/Pet" } } } }, "put": { "summary": "Update an existing pet.", "description": "Update an existing pet by Id.", "operationId": "updatePet", "consumes": ["application/json"], "parameters": [ { "name": "petId", "in": "path", "description": "Pet id to Update", "required": true, "type": "integer", "format": "int64" }, { "name": "body", "in": "body", "description": "Update an existent pet in the store", "required": true, "schema": { "$ref": "#/definitions/Pet" } } ], "responses": { "200": { "description": "Successful operation", "schema": { "$ref": "#/definitions/Pet" } } } }, "delete": { "summary": "Deletes a pet.", "description": "Delete a pet.", "operationId": "deletePet", "parameters": [ { "name": "petId", "in": "path", "description": "Pet id to delete", "required": true, "type": "integer", "format": "int64" } ], "responses": { "200": { "description": "Pet deleted" } } } } }, "definitions": { "Pet": { "type": "object", "required": ["name"], "properties": { "id": { "type": "integer", "format": "int64", "example": 10 }, "name": { "type": "string", "example": "doggie" }, "status": { "type": "string", "description": "pet status in the store", "enum": ["available", "pending", "sold"] } } } } } ```