openapischemas-j9九游会登录

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参数	支持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规范示例

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"]
        }
      }
    }
  }
}

父主题：

下一篇：mcp servers

意见反馈

文档内容是否对您有帮助？

提交成功！非常感谢您的反馈，我们会继续努力做到更好！您可在查看反馈及问题处理状态。

系统繁忙，请稍后重试

如您有其它疑问，您也可以通过华为云社区问答频道来与我们联系探讨