OpenAPI Schema：如何把一个 HTTP API 变成可执行的插件工具
上一篇讲到，PaiFlow 通过 Link 统一连接外部工具。
但这里会有一个问题：
Link 怎么知道一个工具到底应该怎么调用？
比如一个天气接口，Link 并不知道：
请求地址是什么？
GET 还是 POST？
参数放 Query 还是 Body？
需不需要鉴权？
返回结果长什么样？
所以需要一份机器可以理解的接口说明书。
这个东西就是：
OpenAPI Schema。
1. Schema 本质上是什么
可以把 OpenAPI Schema 理解成：
HTTP API 的标准化使用说明书。
普通开发者看接口文档，然后手写代码调用。
而 Link 做的事情是：
读取 Schema
↓
理解 API 怎么调用
↓
自动构造 HTTP 请求
↓
执行工具
所以：
Schema 是外部 API 和 Link 之间的契约。
2. 为什么需要 Schema
假设有一个 TTS 接口：
POST https://api.xxx.com/v1/tts
请求参数：
{
"text": "你好",
"voice": "Cherry"
}
还需要：
Authorization
如果没有 Schema，Link 根本不知道这些信息。
有了 Schema 后，就可以描述：
Server
→ https://api.xxx.com
Path
→ /v1/tts
Method
→ POST
Body
→ text、voice
Security
→ Authorization
于是 Link 就可以根据描述动态调用这个接口。
3. OpenAPI 最核心的几个字段
一份 Schema 看起来可能很长，但真正核心的其实没有多少。
可以记成：
去哪调用
调用什么
参数怎么传
怎么鉴权
返回什么
分别对应下面这些字段。
servers：请求发到哪里
例如：
servers:
- url: https://api.xxx.com
表示：
API 服务地址
=
https://api.xxx.com
paths：调用哪个接口
例如：
paths:
/v1/weather:
get:
表示：
GET /v1/weather
如果是：
/v1/tts:
post:
就是：
POST /v1/tts
所以：
server + path + method
基本就确定了一次 HTTP 请求的目标。
4. operationId：接口的唯一名字
一个工具可能不只有一个接口。
例如天气工具可能提供：
查询当前天气
查询天气预报
查询空气质量
所以需要给每一个操作一个名字：
getCurrentWeather
getForecast
getAirQuality
这就是：
operationId
可以简单理解成：
toolId
→ 找到哪个工具
operationId
→ 找到工具里的哪个接口
有点像：
类
+
方法
5. 参数到底放哪里
HTTP 参数常见有四种位置：
path
query
header
body
Path 参数
例如：
/users/123
这里的：
123
就是 Path 参数。
通常 Schema 会写：
/users/{id}
Query 参数
例如：
/weather?city=beijing&page=1
这里：
city
page
就是 Query 参数。
一般适合：
查询条件
分页
过滤
排序
Header 参数
例如：
x-trace-id
x-app-id
这些通常放在 HTTP Header 中。
RequestBody
POST、PUT 这类接口经常会使用 Body。
例如：
{
"text": "你好",
"voice": "Cherry"
}
OpenAPI 中通过：
requestBody
描述。
所以以后看到参数时，第一反应可以问：
这个参数最终应该放在 HTTP 请求哪里？
理解起来就简单很多。
6. JSON Schema 又是什么
OpenAPI 负责描述：
API 怎么调用。
JSON Schema 更偏向描述：
数据长什么样。
例如：
{
"type": "object",
"required": ["text"],
"properties": {
"text": {
"type": "string"
}
}
}
意思就是：
这是一个对象
↓
里面有 text
↓
text 是字符串
↓
text 必填
所以可以这样理解：
OpenAPI
├── 地址
├── Method
├── 参数位置
├── 鉴权
└── RequestBody
↓
JSON Schema
├── 字段
├── 类型
└── 是否必填
两者经常一起出现，但职责不同。
7. Security：怎么鉴权
大部分第三方 API 都需要鉴权。
常见两种：
API Key
Bearer Token
例如：
x-api-key: xxx
或者：
Authorization: Bearer xxx
OpenAPI 可以描述：
认证类型
认证放在哪
Header 名叫什么
真正的密钥一般不会直接硬编码在 Schema 中，而是由系统单独保存。
运行时：
读取 Schema
↓
知道需要什么认证
↓
读取真实密钥
↓
放入 Header
↓
发送请求
这就是 Schema 和运行时鉴权之间的关系。
8. responses：工具会返回什么
Schema 不只描述请求，也可以描述响应。
例如 TTS 返回：
{
"audio": {
"url": "xxx.wav"
}
}
Schema 可以描述：
audio
└── url:string
这样系统就知道：
这个工具执行之后，大概能获得什么数据。
这些数据后续又可以进入 Workflow 的变量池，继续被后面的节点使用。
9. 从 Schema 到真实 HTTP 请求
这是最值得理解的一条链。
假设 Schema 描述：
server
= https://api.xxx.com
path
= /weather
method
= GET
city
= query 参数
Workflow 传入：
{
"city": "北京"
}
Link 最后就可以拼成：
GET https://api.xxx.com/weather?city=北京
整个过程就是：
OpenAPI Schema
+
Workflow 参数
↓
Schema Parser
↓
HTTP Request
↓
HttpExecutor
↓
第三方 API
所以 Schema 的本质价值是：
把一个抽象的工具描述，转换成可以真正执行的 HTTP 请求。
10. x-display、x-from 是什么
有时候 Schema 里面还会看到：
x-display
x-from
这种以：
x-
开头的字段，一般表示：
OpenAPI 的自定义扩展字段。
它们通常不是通用 OpenAPI 的核心能力，而是项目自己定义的业务规则。
例如可能用来描述：
字段是否展示
参数来自哪里
UI 怎么渲染
因此学习时要区分：
type
properties
required
operationId
这些属于核心规范。
而：
x-display
x-from
更偏 PaiFlow 自己的扩展。
11. 什么时候需要自己写 Schema
最典型的场景就是：
把一个普通 HTTP API 接入工作流。
比如要接：
天气 API
TTS
OCR
搜索
企业内部接口
第三方 SaaS
一般步骤都是：
阅读 API 文档
↓
确定 Server
↓
确定 Path
↓
确定 Method
↓
确定参数位置
↓
确定 RequestBody
↓
确定鉴权方式
↓
确定返回结构
↓
写成 OpenAPI Schema
↓
注册到 Link
之后 Workflow 就可以把它当成普通 Tool 使用。
12. 最值得沉淀的架构思想
这一套机制真正有价值的地方，不是学会写 YAML 或 JSON。
而是：
通过描述代替硬编码。
如果没有 Schema：
新增一个 API
↓
写一套调用代码
↓
重新开发
有了 Schema：
新增一个 API
↓
新增一份描述
↓
通用执行器负责执行
这就是典型的：
声明式设计。
系统关注的是：
你告诉我这个 API 是什么
而不是：
你必须重新写代码告诉我怎么执行
总结
OpenAPI Schema 可以简单理解成：
外部 HTTP API 的机器使用说明书。
它主要描述：
servers
→ 请求发到哪里
paths + method
→ 调哪个接口
operationId
→ 这个操作叫什么
parameters
→ 参数放哪里
requestBody
→ Body 长什么样
security
→ 怎么鉴权
responses
→ 返回什么
PaiFlow 的 Link 读取这份 Schema，再结合 Workflow 传进来的参数，就能动态构造并执行真实的 HTTP 请求。
上一篇解决的是：
为什么需要 Link。
这一篇解决的是：
怎么让一个普通 HTTP API 变成 Link 可以执行的工具。
真正值得记住的一句话是：
Schema 让“接入一个新工具”从写大量调用代码，变成描述这个工具应该怎么被调用。