上一篇提到了 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]

2.2 参数定义

参数来源常见有四种：path、query、header、body。前三种走 parameters，body 走 requestBody。

path 参数就是路径里带变量，比如 /v1/user/{id}。在实际调用时，URL 可能是这样的：/users/123，其中123就是userId的值。

paths:
  /v1/user/{id}:
    get:
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string

query 参数就是 ?a=1&b=2 这种，通常用于过滤、分页等操...