✅插件Schema定义规范：OpenAPI必备字段与HTTP工具Schema实战

上一篇提到了 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版本
info:                    # API基本信息
  title: API标题
  version: 版本号
  x-is-official: true/false # 是否为官方插件工具
servers:                 # 服务器地址
  - url: 服务地址
  - description: 描述
paths:                   # API路径定义
  /path:                 # 具体路径
    get:                 # HTTP方法，常见的为get/post
      summary: 操作摘要
      operationId: 操作ID
      parameters:        # 参数定义
        - name: 参数名
          in: 参数位置
          schema: 参数结构
      security:
        - 安全考研规则
      responses:         # 响应定义
        '200':
          description: 成功响应
          content:
            application/json:
              schema: 响应结构

2.Schema定义详解

2.1 Paths和Operations

一个工具可以只有一个 API，也可以多个。多数场景建议一个工具对应一个核心 Operation。以 GET 为例，写法大概这样：

paths:
  /v1/weather:
    get:
      summary: 查询天气
      operationId: getWeather
      parameters:
        - name: city
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  city:
                    type: string
                  temp:
                    type: number
                required: [city, temp]