📚 课程目录第3章 OpenAPI规范入门

OpenAPI 规范入门：从零搭建你的第一个契约文档

说实话，我刚接触 API 设计那会儿，最头疼的就是「文档」。接口写完了，文档要么忘了更新，要么跟代码对不上。后来我发现了 OpenAPI 规范——它不光是文档，更是 API 的「契约」。今天我们就从最基础的东西聊起。

OpenAPI 3.0 到底是个啥？

简单说，OpenAPI 是一套标准。它用结构化的方式描述你的 API：有哪些路径、接收什么参数、返回什么数据。你想想看，如果前端和后端都照着同一份 OpenAPI 文档开发，联调时能少吵多少架？

我个人习惯把 OpenAPI 文档看作「API 的身份证」。它不依赖任何编程语言，谁都能看懂。而且工具链特别丰富——从文档生成、Mock 服务到代码生成，一条龙搞定。

  核心价值： OpenAPI 3.0 让 API 设计从「口头约定」升级为「机器可读的契约」。

YAML 和 JSON：选哪个？

OpenAPI 支持两种格式：YAML 和 JSON。我个人的建议是——写文档用 YAML，传输用 JSON。为什么？

特性	YAML	JSON
可读性	高，缩进结构一目了然	一般，括号多了容易晕
注释支持	支持 # 注释	不支持
文件大小	相对紧凑	稍大（引号、逗号多）
工具兼容性	大部分工具都支持	原生支持最广

嗯，这里要注意：YAML 对缩进极其敏感。我曾经因为一个空格没对齐，排查了整整两个小时。所以写 YAML 时，建议用 2 个空格缩进，别用 Tab。

YAML 基础语法速览

你不需要成为 YAML 专家，掌握这几点就够了：

键值对： name: 张三（冒号后要加空格）
列表： 用短横线 - item1
嵌套： 缩进表示层级
多行字符串： 用 | 保留换行，> 折叠换行

# 一个简单的 YAML 示例
title: 用户服务
version: "1.0.0"
endpoints:
  - path: /users
    method: GET
    description: 获取用户列表
  - path: /users/{id}
    method: GET
    description: 获取单个用户

OpenAPI 文档的核心结构

一份标准的 OpenAPI 3.0 文档，包含这几个顶层字段：

openapi — 规范版本号，目前固定写 3.0.3
info — API 的元信息（标题、版本、描述）
servers — 服务器地址列表
paths — 所有 API 路径的定义（核心中的核心）
components — 可复用的数据模型和参数

说白了，你只要把这五个部分填好，一份可用的 API 契约就出来了。

编写你的第一个 OpenAPI 文档

我们来写一个「用户管理」API。先看完整示例：

openapi: "3.0.3"
info:
  title: 用户管理 API
  description: 用于管理平台用户的 RESTful 接口
  version: "1.0.0"
servers:
  - url: https://api.example.com/v1
    description: 生产环境
paths:
  /users:
    get:
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        "200":
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/User"
  /users/{userId}:
    get:
      summary: 获取单个用户
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: 用户详情
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
      required:
        - id
        - name

小技巧： 用 $ref 引用 components 里的模型，可以避免重复定义。我习惯把所有数据结构都放在 components 里，paths 里只写引用。

SVG 图解：OpenAPI 文档结构

下面这张图帮你理清各个部分的关系：

避坑指南：我踩过的几个坑

写 OpenAPI 文档时，有几个地方特别容易出错：

版本号格式： openapi: "3.0.3" 必须用字符串，不能写成数字 3.0.3。YAML 会把 3.0 解析成浮点数，变成 3.0 而不是 "3.0.3"。
路径参数： 路径里的 {userId} 必须在 parameters 里定义，并且 in: path 要写对。我曾经漏掉这个，结果生成的客户端代码一直报错。
响应状态码： 状态码必须用字符串形式，比如 "200" 而不是 200。YAML 会把 200 当成数字，导致某些工具解析失败。

特别注意： 不要手写 $ref 路径时想当然。我见过有人把 #/components/schemas/User 写成 #/components/schema/User（少了个 s），结果整个文档失效。这种错误特别隐蔽。

验证你的文档

写完之后怎么知道对不对？我推荐两个工具：

Swagger Editor： 在线编辑器，左边写 YAML，右边实时渲染文档。还能做语法校验。
OpenAPI CLI： 命令行工具，可以集成到 CI/CD 流程里。每次提交代码时自动验证。

我个人习惯先用 Swagger Editor 快速验证，确认没问题后再提交到代码仓库。这样能避免很多低级错误。

小结

OpenAPI 3.0 其实不复杂。你只要记住：info 写元数据，servers 写地址，paths 写接口，components 写模型。把这四个部分填好，一份可用的 API 契约就出来了。

嗯，今天的内容就到这儿。你试着写一个自己的 API 文档吧——哪怕只是一个简单的「健康检查」接口也行。动手写一遍，比看十遍都管用。