01 · 认识 Swagger / OpenAPI：它到底是什么

生活类比：Swagger 就是餐厅的菜单 + 厨房的工单系统——所有顾客（前端）都看同一本菜单点单，所有厨师（后端）都看同一张工单出菜。再也不会出现"我以为你要的是芝士汉堡，结果你想要的是芝士牛排"。

1. 用一张图说清楚 Swagger 在干嘛

没有 Swagger 的世界（别笑，很多团队还活在这里）：

前端：    "刘哥，登录接口是 /login 还是 /api/login？"
后端：    "你看一下 Word 文档"
前端：    "Word 文档说返回 token，但我收到的是 access_token"
后端：    "哦那个文档是上周的，我代码改了"
前端：    😡
测试：    "我还在用月初的 Postman 集合，已经全 404 了"
产品：    "项目验收明天，文档呢？"

加上 Swagger 的世界：

                      ┌───────────────────────────────┐
                      │          openapi.yaml         │
                      │   （唯一事实源 / SSOT）         │
                      └────────────┬──────────────────┘
                                   │
            ┌──────────────────────┼──────────────────────┐
            ▼                      ▼                      ▼
   ┌────────────────┐    ┌────────────────┐    ┌────────────────┐
   │  Swagger UI    │    │  代码生成器     │    │  Mock 服务      │
   │  (在线文档)    │    │  前端 SDK      │    │  (Prism)       │
   │                │    │  后端骨架       │    │                │
   └────────────────┘    └────────────────┘    └────────────────┘
            │                      │                      │
            ▼                      ▼                      ▼
        前端 / 测试 / 产品看        前端 / 后端写代码        前端等不及后端时调用

一句话：openapi.yaml 是一份"机器能看懂的接口合同"，其他工具都是从它派生出来的便利。

2. Swagger 解决的"四大本职痛点"

┌───────────────────────────────────────────────────────────────┐
│  ① 文档过期         →  代码即文档，文档随代码自动更新           │
│  ② 沟通成本高       →  前后端看同一个 URL，一目了然             │
│  ③ 联调慢           →  前端用 Mock 自测，后端自己跑 Postman      │
│  ④ 类型不安全       →  TypeScript SDK 自动生成，IDE 全程提示    │
└───────────────────────────────────────────────────────────────┘

类比 · 麦当劳的标准化菜单

Swagger 概念	麦当劳类比
`openapi.yaml`	全球统一的菜单（巨无霸 = Big Mac，全世界统一）
`paths`	菜单上的菜品列表（巨无霸 / 麦辣鸡腿堡 / 薯条）
`parameters`	选规格（中份 / 大份 / 加酱）
`requestBody`	你点单时填的小票（套餐 + 加料 + 备注）
`responses`	点单后收到什么（汉堡 + 找零 + 小票）
`components/schemas`	通用配料表（牛肉饼、酸黄瓜、特调酱被多个汉堡复用）
`security`	会员卡（凭卡享会员价）
Swagger UI	把菜单贴到墙上让所有人看（门店招牌灯箱）
Codegen	收银机系统（按菜单自动生成订单输入界面）

核心点：Swagger 自己不写业务代码，它是那本让所有人对齐的"菜单"。

3. 为什么 Swagger 这么火？三个硬核原因

3.1 跨语言、跨团队的"接口合同"

OpenAPI 是 YAML/JSON 文本，任何语言都能解析。换句话说：

后端是 Java，前端是 TypeScript，移动端是 Swift / Kotlin
测试团队用 Python 的 schemathesis 跑接口模糊测试
DevOps 用 Spectral 在 CI 里检查文档质量

只要大家都认 openapi.yaml，就能各自发挥。

3.2 工具生态爆炸

openapi.yaml
    │
    ├── Swagger UI            (浏览文档)
    ├── Swagger Editor        (在线编辑器)
    ├── Redoc                 (更漂亮的文档)
    ├── Stoplight Studio      (可视化编辑)
    ├── Prism                 (Mock 服务)
    ├── openapi-generator     (生成 50+ 语言 SDK)
    ├── Postman / Insomnia    (一键导入测试集合)
    ├── Spectral              (质量检查 / Lint)
    ├── schemathesis          (基于 schema 的模糊测试)
    └── API Gateway           (Kong / APISIX 直接吃 yaml)

任何一个流行的 API 工具，几乎都支持 OpenAPI。这就是行业标准的力量。

3.3 大厂都在用

公司	公开的 OpenAPI 文档地址
GitHub	https://github.com/github/rest-api-description
Stripe	https://github.com/stripe/openapi
AWS	https://github.com/aws/aws-sdk-js-v3 (内部源自 OpenAPI)
Twilio	https://github.com/twilio/twilio-oai
阿里云	大部分开放平台 API 都有 OpenAPI 描述

看一眼 Stripe 的 yaml，就能感受 "好接口文档" 的样子——这是后续章节的目标。

4. Swagger vs 其他文档方式（一张表看完）

对比项	OpenAPI/Swagger	Word/语雀手写	Markdown 表格	Postman 集合	gRPC + protobuf
准确性	⭐⭐⭐⭐⭐ (代码即文档)	⭐ (秒过期)	⭐⭐ (人肉同步)	⭐⭐⭐ (跑过才知)	⭐⭐⭐⭐⭐ (强类型)
可读性	⭐⭐⭐⭐ (UI 漂亮)	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐	⭐⭐ (proto 编译需)
可运行	⭐⭐⭐⭐⭐ (Try it out)	❌	❌	⭐⭐⭐⭐⭐	⭐⭐⭐ (需工具)
自动化	⭐⭐⭐⭐⭐ (生成代码)	❌	❌	⭐⭐⭐ (集合)	⭐⭐⭐⭐⭐ (强)
学习成本	中	低	极低	低	中
适合场景	REST API 通用	内部约定	简单项目	测试 + 文档兼用	微服务 RPC

结论：业内默认 = REST API 用 OpenAPI / Swagger，微服务内部 RPC 用 gRPC。

5. Swagger 的"演化史"——一段故事

2010 ─────► Tony Tam 在 Wordnik（在线英语词典）写 Swagger，
            为的是给前端工程师生成 SDK
2011 ─────► Swagger 1.0 开源，迅速火遍美西硅谷
2014 ─────► Swagger 2.0 发布（业界第一次形成事实标准）
2015 ─────► SmartBear 收购 Swagger，宣布捐"规范"给 Linux 基金会
            从此规范叫 OpenAPI Specification (OAS)
2017 ─────► OpenAPI 3.0 发布（结构大改，引入 components / requestBody）
2021 ─────► OpenAPI 3.1 发布（完全兼容 JSON Schema 2020-12）
2024+ ────► AI 时代：ChatGPT Plugins、Function Calling、MCP 都在用 OpenAPI

冷知识：现在 ChatGPT 的"插件 / Actions"用一份 OpenAPI 描述告诉 LLM"我有什么 API、参数怎么传"。Swagger 已经从 API 文档进化成了 AI 的对接协议。

6. OpenAPI 2.0（Swagger 2.0） vs OpenAPI 3.0：差在哪

老项目里 yaml 第一行是 swagger: "2.0"，新项目都是 openapi: 3.0.x 或 3.1.x。新项目无脑选 3.0+。

维度	OpenAPI 2.0 (Swagger 2)	OpenAPI 3.0 / 3.1
顶层字段	`swagger: "2.0"`	`openapi: 3.0.3`
服务器地址	`host` + `basePath` + `schemes`	`servers` 数组
请求体	没有独立块，混在 parameters 里	独立的 `requestBody`
复用	`definitions`	`components` (schemas/parameters/responses/securitySchemes/...)
多 MIME 类型	单一 `consumes` / `produces`	每个 contentType 一个
OAuth2	配置丑、不直观	重写、字段清晰
JSON Schema 兼容	部分	3.1 完全兼容

7. 你需要什么前置知识？

知识	是否必备	不会能学吗？
HTTP 基础（请求/响应/状态码/方法）	✅ 必备	不会会很懵
YAML 基本语法（缩进、key-value）	✅ 必备	学 10 分钟就够
JSON 数据结构	✅ 必备	跟 yaml 互通
REST API 风格（资源/动词/版本）	⭕ 推荐	不会就当跟着学
后端任意一门语言	⭕ 推荐	不会能写文档，但生成代码就用不上
TypeScript	⭕ 推荐	第 8 章生成前端 SDK 时强烈推荐熟悉

8. 接下来怎么学

你在这里
   ↓
01 ─►  02 安装  ─►  03 文件结构  ─►  04 路径  ─►  ……

章末小测（先猜，下一章对答案）：

Swagger 和 OpenAPI 是同一个东西吗？
openapi.yaml 第一行该写什么？
Swagger UI 的地址（在线版）是什么？
一份 yaml 能同时给前端和后端生成代码吗？

9. 章末面试题速览（详见 qa.md）

章节面试题以最简短结论 + 一个反问形式记忆，详细参考答案在 qa.md。

Swagger 和 OpenAPI 的关系？ → OpenAPI 是规范、Swagger 是工具家族；2015 年规范捐给 Linux 基金会改名 OpenAPI。
为什么用 Swagger，不用 Word 文档？ → "代码即文档"，永不过期；可生成 SDK、Mock、测试集合，全链路自动化。
OpenAPI 3.0 比 2.0 强在哪？ → servers 数组、独立 requestBody、components 结构化复用、对 OAuth2 / JSON Schema 友好。

🎬 可视化演示

下方 demo 用动画展示**「没有 Swagger vs 有 Swagger」**时前端、后端、测试是如何沟通和工作的——你会清楚看到 openapi.yaml 像一份"接口合同"那样把所有人对齐。

→ 打开 01_intro/demo.html

🎬 可视化演示

演示加载缓慢或样式异常？点此在新标签页打开 ↗

01 · 认识 Swagger / OpenAPI：它到底是什么 ​

1. 用一张图说清楚 Swagger 在干嘛 ​

2. Swagger 解决的"四大本职痛点" ​

类比 · 麦当劳的标准化菜单 ​

3. 为什么 Swagger 这么火？三个硬核原因 ​

3.1 跨语言、跨团队的"接口合同" ​

3.2 工具生态爆炸 ​

3.3 大厂都在用 ​

4. Swagger vs 其他文档方式（一张表看完） ​

5. Swagger 的"演化史"——一段故事 ​

6. OpenAPI 2.0（Swagger 2.0） vs OpenAPI 3.0：差在哪 ​

7. 你需要什么前置知识？ ​

8. 接下来怎么学 ​

9. 章末面试题速览（详见 qa.md） ​

🎬 可视化演示 ​

🎬 可视化演示 ​

01 · 认识 Swagger / OpenAPI：它到底是什么

1. 用一张图说清楚 Swagger 在干嘛

2. Swagger 解决的"四大本职痛点"

类比 · 麦当劳的标准化菜单

3. 为什么 Swagger 这么火？三个硬核原因

3.1 跨语言、跨团队的"接口合同"

3.2 工具生态爆炸

3.3 大厂都在用

4. Swagger vs 其他文档方式（一张表看完）

5. Swagger 的"演化史"——一段故事

6. OpenAPI 2.0（Swagger 2.0） vs OpenAPI 3.0：差在哪

7. 你需要什么前置知识？

8. 接下来怎么学

9. 章末面试题速览（详见 qa.md）

🎬 可视化演示

🎬 可视化演示