更新时间：2026-06-11 GMT+08:00
OpenAPI Schemas
OpenAPI是用于描述 RESTful API 的广泛使用标准。Gateway支持用于定义API targets 的 OpenAPI 3.0 和Swagger 2.0 规范。
OpenAPI targets将您的Gateway连接到使用 OpenAPI 规范定义的 REST APIs。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参数 |
|
|
| header参数 |
|
|
| query参数 |
| 不支持Object |
| cookie参数 | - | 不支持 |
| 请求体 |
| 不支持application/xml等格式 |
| 响应体 | - | 不支持 |
OpenAPI 模式规范
- 在配置 OpenAPI targets时，有关 OpenAPI 规范格式的信息，请参见 OpenAPI Specification。
- 支持的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"] } } } } }
- openapi 3.0
父主题： 支持的Target类型
