上一篇提到了 Schema，可能有一些球友不太了解这玩意到底是个啥，没法抽象，我们这里就花点时间来介绍一下，主要还是和 OpenAI 的规范有关系。这篇内容会教会大家：

1）看懂一份 OpenAPI 文档里哪些字段是必须的，哪些是可选的

2）能写出一个完整的 HTTP 工具 Schema，让插件服务可以稳定调用

1.什么是OpenAPI规范

OpenAPI，本质上就是一份 API 说明书。我们把接口怎么调、参数怎么传、返回长啥样、要不要鉴权，全写在这份 Schema 里。

对于插件服务来说，插件不关心这个工具到底是查天气、发邮件还是抓网页。它只认一件事：这份 OpenAPI Schema 里有没有写清楚怎么调用，照着拼请求、发请求、拿响应结果，把工具当成标准化的能力去用。

OpenAPI 里最关键的几个概念：

• Path：也就是接口路径，比如 /v1/search

• Operation：某个 Path 的方法定义，比如 GET /v1/search 或 POST /v1/search

• Parameter：也就是入参，可能来自路径、查询串、请求头

• RequestBody：也就是请求体，通常是 POST PUT 这类方法，用的 JSON

• Response：也就是响应体

• Schema：用 JSON Schema 的方式描述参数和响应的数据结构

• Security：鉴权规则，告诉调用方要怎么带 token 或 apiKey

在 PaiFlow 中，一份完整的 OpenAPI 文档长这样：

openapi: 3.0.0          # OpenAPI版本
...