主题
Swagger / OpenAPI 从 0 到 1 · 学习总览
一句话开篇：Swagger 就像餐厅的"菜单 + 点单小票 + 厨房工单"三合一——前端（顾客）照着菜单点单，后端（厨房）照着工单出菜，所有人对"接口长什么样、传什么、返回什么"再也不用扯皮。
这套笔记面向完全没碰过接口文档的小白，把 Swagger / OpenAPI 拆成 10 个由浅入深的章节，每章配：
- 🌟 生活类比 — 用餐厅菜单、快递单、银行转账讲清概念
- 📚 知识点 — 从 YAML 字段到代码生成，逐层深入
- 🎬 HTML Demo — 在浏览器里就能跑的可视化演示
- 🛠️ 实战代码 — 可以直接复制到项目的
openapi.yaml/ 后端注解 - 🎤 面试问题 — 大厂前后端高频题（章末 + 总集
qa.md）
1. 为什么前端 / 后端 / 测试 / 产品都该会 Swagger？
┌──────────────────────────────────────────────────────┐
│ │
产品 ─┐ │
│ │
前端 ─┼─► openapi.yaml ◄─┬─► 自动生成 API 文档（Swagger UI）│
│ (单一事实源) ├─► 自动生成前端 TypeScript SDK │
后端 ─┤ ├─► 自动生成后端 Controller 骨架 │
│ ├─► 自动生成 Postman 测试集合 │
测试 ─┘ └─► 自动生成 mock 服务 │
└──────────────────────────────────────────────────────┘前端工程师：再不用追着后端问"这个字段类型是啥？必传吗？"，类型直接生成 .ts，IDE 全程提示。 后端工程师：写代码顺手出文档，文档永远跟代码同步，对接前端只需甩一个 URL。 测试 / QA：直接拿文档跑 Postman / Newman 接口测试，参数、断言一键就绪。 产品 / 项目经理：在 Swagger UI 上能看完整接口列表，对齐进度不再靠口口相传。
不夸张地说：只要有前后端协作，就该有一份 OpenAPI 文档。Stripe、GitHub、AWS、阿里云的开放文档，背后都是 OpenAPI 规范。
2. Swagger 与 OpenAPI 到底什么关系？（先解释清楚，不绕）
2010 ─────► Swagger 诞生（Wordnik 公司，作者 Tony Tam）
2015 ─────► SmartBear 收购 Swagger，并把"规范"捐给 Linux 基金会
从此，"规范"改名 OpenAPI Specification (OAS)
"工具集"保留 Swagger 品牌（Swagger UI / Editor / Codegen）
2017 ─────► OpenAPI 3.0 发布
2021 ─────► OpenAPI 3.1 发布（完全兼容 JSON Schema）| 名字 | 是什么 |
|---|---|
| OpenAPI | "规范 / 协议"——一份 YAML/JSON 怎么写 |
| Swagger | "工具家族"——UI、Editor、Codegen |
一句话：OpenAPI 是规范，Swagger 是按这个规范做的工具。日常口语两者经常混用，本笔记也不严格区分，但你心里要清楚。
3. 学习路线图
┌─────────────────────────────────────────────────────────────┐
│ Stage 1 · 入门：先搞清楚 Swagger 到底是个啥 │
│ 01 介绍 02 安装 / 启动 Swagger UI │
│ │
│ Stage 2 · 上手：会写一份 openapi.yaml │
│ 03 文件结构 04 路径与操作 05 参数 │
│ │
│ Stage 3 · 进阶：能写出生产级文档 │
│ 06 请求体 / 响应体 / 复用 Schema │
│ 07 鉴权（Token / OAuth2） │
│ │
│ Stage 4 · 工程化：让文档帮你写代码 │
│ 08 代码生成（前端 SDK / 后端骨架 / mock） │
│ 09 与后端框架集成（Spring / Express / NestJS / FastAPI） │
│ │
│ Stage 5 · 实战 + 面试 │
│ 10 一份电商 API 全套示例 │
│ QA 高频面试题 │
└─────────────────────────────────────────────────────────────┘推荐顺序：第一遍按章节顺序通读 → 第二遍直接做实战章节（10）+ 面试题（qa.md）。
4. 章节清单
| # | 章节 | 一句话讲透 | 必备程度 |
|---|---|---|---|
| 01 | 认识 Swagger/OpenAPI | 它到底是什么、能干嘛、怎么火起来的 | ⭐⭐⭐⭐⭐ |
| 02 | 安装与第一次启动 | Swagger UI / Editor / Docker，5 分钟跑起来 | ⭐⭐⭐⭐⭐ |
| 03 | OpenAPI 文件结构 | openapi / info / paths / components 四大块 | ⭐⭐⭐⭐⭐ |
| 04 | 路径与操作 | GET/POST/PUT/DELETE 七种 HTTP 方法怎么写 | ⭐⭐⭐⭐⭐ |
| 05 | 参数详解 | path/query/header/cookie 四种位置全讲透 | ⭐⭐⭐⭐⭐ |
| 06 | 请求体 & 响应体 & Schema 复用 | components/schemas 才是 Swagger 的灵魂 | ⭐⭐⭐⭐⭐ |
| 07 | 鉴权 Security | apiKey / bearer / OAuth2 / OpenID 配置全集 | ⭐⭐⭐⭐ |
| 08 | 代码生成 | 一份 yaml → 前端 TS SDK + Mock + 后端骨架 | ⭐⭐⭐⭐⭐ |
| 09 | 与后端框架集成 | Spring / Express / NestJS / FastAPI 注解写法对比 | ⭐⭐⭐⭐ |
| 10 | 实战：电商 API 完整文档 | 一份生产可用的 openapi.yaml，端到端讲解 | ⭐⭐⭐⭐⭐ |
| QA | 高频面试题 | 30+ 真题 + 详细参考答案 | ⭐⭐⭐⭐⭐ |
5. 学完之后你能做什么
- ✅ 看到任意一份
openapi.yaml，能知道每行在干什么 - ✅ 给团队搭一套 "代码即文档" 的工作流，再也不写过期 Word 文档
- ✅ 用一份 yaml 在 5 分钟内同时给前后端生成代码 / Mock 服务
- ✅ 给自己的 Spring Boot / FastAPI / Express 项目挂上 Swagger UI
- ✅ 在面试里把 "OpenAPI 3.0 vs 2.0"、"为什么用 Swagger"、"代码生成怎么落地" 讲得明明白白
6. 用什么环境跟着学？
最低成本（推荐）：在线版 Swagger Editor，0 安装：
👉 https://editor.swagger.io本地版（推荐生产用）：装 Docker，一句话起 Swagger UI：
bash
docker run -d \
--name swagger-ui \
-p 8080:8080 \
-v $PWD/openapi.yaml:/spec/openapi.yaml \
-e SWAGGER_JSON=/spec/openapi.yaml \
swaggerapi/swagger-ui详细安装方式见 02 章 · 安装与第一次启动。
7. 一句话总结这套笔记
从"接口文档靠口头"到"一份 yaml 生成全套代码 + 文档 + Mock"，这 10 章 + 30 道题就是路。