4.3 OpenAPI 文档：契约的成文版本

4.3 OpenAPI 文档：契约的成文版本

本节摘要：OpenAPI（原 Swagger）规范用一份语言无关的 YAML/JSON 把接口"写成正式文本"，再由工具生成可交互的在线文档。本节讲从规范文件的 theme 结构、到交互文档、再到自动生成的流水线，并给出"机器可读成文后"，如何用它做契约评审的火线演练。

学习目标

阅读完本节，你应当能够：

1. 说清 OpenAPI 规范文件的核心结构：openapi 字段、paths、components。
2. 用一份最小 spec 描述一个资源及其方法、状态码、请求响应 schema。
3. 从 spec 生成交互式文档，并接入团队契约评审。
4. 说明"机器可读成文"相比手写 Markdown 文档的优势。

文档是"契约的成文版本"

车间一谈到自描述消息时，强调的是"每条消息自带如何处理的信息"。但光靠消息还不够——客户端（尤其外部开发者）需要在发第一笔请求前，就能看到"这份接口到底长什么样、接受什么、返回什么"。

OpenAPI 就是这份"成文版本"：它把接口的技术契约，用一种语言无关、机器可读的格式固定下来。妙处在于它是"单一可信源"——文档、测试、客户端 SDK 都能从这份规范生成，而不必各写一份、各对错。

把"手写 Markdown"和"机器可读 spec"摆在一起对照，差别就在一句话：前者是给人读的说明书，改多改少没人校验；后者是一份可被程序解析、校验、生成的施工图，改错了工具就报错。正因为可被机器消费，它才有能力同时驱动文档、SDK 和测试三端，避免"三处各说各话"的无序。

二、一份最小 spec 长什么样

OpenAPI 文件的核心结构，用三块理解就够：

• openapi：版本声明。
• paths：按路径列出每个方法、参数、请求体、响应与状态码。
• components：抽出来复用的 schema（数据结构定义），供 paths 和各 ref 引用。

最小 spec 示例：

openapi: 3.0.0
info:
  title: 书店接口
  version: "1.0.0"
paths:
  /book/{id}:
    get:
      summary: 获取书详情
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Book"
components:
  schemas:
    Book:
      type: object
      properties:
        id: { type: integer }
        title: { type: string }
        author: { type: string }
​

读法：GET /book/{id} 会返回一个 Book schema 的 JSON。这份 YAML 就是书接口的"施工蓝图"，任何工具都能解析它。

OpenAPI 从规范一路到成品辐射成文档、SDK、测试三端，一图看懂"单一可信源"：

图：OpenAPI 单一可信源辐射

三、从规范到交互文档的流水线

规范写好后，工具链把它变成能点、能试、能生成代码的生态：

• 规范校验：先查 spec 合法，才谈生成。
• 交互文档 UI：自动渲染成带"试运行"按钮的在线文档，外部开发者能直接在页面上发请求看响应。
• 生成 SDK：把 spec 变成各语言的客户端代码，消除"手抄文档再写 SDK"的错位。

流水线里最容易松的是"校验"这一环。真正稳的做法是把 spec 校验塞进 CI——每次改动 spec 都跑一次命令，语法错、ref 悬空、字段类型不合法当场红掉，而不是等文档 UI 挂出来才发现。更进一步，可以把 spec 的 diff 纳入评审流程：合并请求里"这次改了哪些接口、哪些是破坏性变更"，用一份规范的变更对比来支撑评审意见，比让评审人自己翻实现要可靠得多。这一步把"成文"从静态产物升级成"每次改动都被机器盯着的活契约"。

四、一次契约评审的火线演练

背景：产品要对订单接口加一个 coupon 字段，打算直接改实现。

操作：开发先在 spec 的订单 schema 里加上 coupon 可选字段，用工具生成最新文档，评审会上按 spec 逐条对齐——前端确认能消费、后端确认 schema 定义无误即可运行、测试按 schema 补用例。

结果：字段改动在"成文版本"里先被确认，客户端与测试按 spec 协同推进，没有出现"前端以为有、后端还没给"的错位。

解读：spec 是第一现场——改动先落在它能被评审、被 diff、被生成的地方，再由它辐射到实现与消费。比起"改了代码，文档忘了同步"，这几乎是纪律层面的质变。

变式：若 spec 一开始就写成 Dead 文档（写完就没人维护，实际实现另起炉灶），这台戏全白搭。所以"成文"必须作为"单一可信源"养着：实现改动必改 spec，spec 改动必生成文档与测试。

⚠️ 常见坑：把 spec 当"上线前补的说明书"，写完没人管、和实现脱节。OpenAPI 的价值建立在"它是单一可信源"上——让它脱节，就等于成文版本失真，回头客户端拿到的是旧图纸。

💡 关键直觉：OpenAPI 把文档从"给人看的作业"升级成"机器可读、可生成、可评审的施工图"。谁让 spec 先行、保持同步，接口交付的后半场就稳了一大半。

本节要点回顾

• 要点一：OpenAPI 用机器可读格式把接口"写死成文"，是单一可信源。
• 要点二：核心结构是 openapi 声明、paths、components 三块。
• 要点三：spec 可生成交互文档、客户端 SDK、测试用例。
• 要点四：改动先落 spec 再辐射到实现与消费，可 diff 可评审。
• 要点五：spec 脱节即文档失真，要作为单一可信源持续维护。
• 要点六：OpenAPI 是"施工图"，评审与生成的双保险都靠它。

成文版本定了，接下来对着它安排验收——API 测试的五个分层把关正式开工。