OpenAPI 自动摄取

这是什么

开放平台「统一能力适配网关」支持把任意 OpenAPI 2.0 / 3.0 文档 自动转换成 REST 工具，直接写入能力总线（kind='rest'）。你不再需要手写每个接口的 httpMethod / path / 参数结构。

工作原理

你的 OpenAPI 文档
   │  parseOpenApi(spec)
   ▼
McpToolDef[]  (name / httpMethod / path / :param / inputSchema)
   │  写入 mcp_capabilities.tools_static (kind='rest', auto_discover=0)
   ▼
/api/mcp 的 tools/list 自动聚合 → 客户端开箱调用

• paths 下每个 method（get/post/put/delete/patch）→ 一个工具
• /users/{id} → path: /users/:id（占位符自动转换）
• path/query/header 参数 + requestBody → inputSchema
• operationId 优先作为工具名；缺失时由 METHOD_Path 推导

三种登记方式

档位	怎么做	适用
Quick	只填 member + upstream_url（MCP 端点），auto_discover=1	上游已暴露标准 MCP Server
Standard（OpenAPI）	在登记请求里附 openapi 字段（对象或 JSON 字符串）	上游有 Swagger 但无 MCP
Full	OpenAPI + 凭据 + Webhook + 发布	完整能力运营

调用示例

curl -X POST https://open.yunjii.cn/api/console/capabilities/register \
  -H "Content-Type: application/json" \
  -H "Cookie: open_sso_token=YOUR_TOKEN" \
  -d '{
    "member": "myapi",
    "label": "我的 REST 服务",
    "upstream_url": "https://myapi.example.com",
    "auth_type": "bearer",
    "auth_secret": "TOKEN",
    "openapi": { "openapi": "3.0.0", "paths": { "/users/{id}": { "get": { "operationId": "getUser", "parameters": [{"name":"id","in":"path","required":true,"schema":{"type":"number"}}] } } } }
  }'

返回：

{ "code": 1, "msg": "已登记/更新", "data": { "member": "myapi", "kind": "rest", "tool_count": 1 } }

随后任何 MCP 客户端连 open.yunjii.cn/api/mcp 的 tools/list，即可看到 myapi__getUser 并直接 tools/call。

说明与边界

• 仅解析一层参数结构（浅展开），深层 $ref 在后续版本支持；遇到无法解析的字段会跳过该字段而非报错。
• 解析结果为空会直接拒绝登记，避免写入空能力。
• 仍兼容原有「手填 tools_static」方式（不传 openapi 时走旧逻辑）。