Swagger 简介（简洁明了版 · 2025最新）
Swagger 是目前全球最流行的 API 文档工具集合，现在官方已全面更名为 OpenAPI，但大家仍然习惯叫它 Swagger。
一句话总结：
Swagger = OpenAPI 规范（设计标准） + 一整套工具（自动生成文档、测试、代码）
核心组成部分
| 名称 | 作用 | 现在常用工具 |
|---|---|---|
| OpenAPI Specification (OAS) | API 的“设计语言”（YAML/JSON 文件） | OpenAPI 3.0 / 3.1（2025主流是3.1） |
| Swagger UI | 把 OpenAPI 文件渲染成漂亮、可交互的文档页面 | 最常见的就是那个绿色界面 |
| Swagger Editor | 在线实时编写和预览 OpenAPI 文件 | https://editor.swagger.io |
| Swagger Codegen / OpenAPI Generator | 根据 OpenAPI 文件自动生成多语言客户端和服务端代码 | 支持 Java、TypeScript、Go、Python 等 50+ 语言 |
| Swagger Core | 各种语言的注解库（在代码里写注释自动生成文档） | 如 springdoc-openapi（Java）、Swashbuckle（.NET）等 |
能解决什么问题？
- 后端写一次代码/注解 → 自动生成永远和代码同步的 API 文档
- 前端/客户端/测试人员直接在浏览器里点一点就能调用接口（带参数、带登录 token）
- 自动生成各种语言的 SDK，减少联调沟通成本
- 接口合同化管理（先写 OpenAPI 再开发，真正实现“契约优先”）
2025 年主流技术栈对应工具（一句话记住）
- Spring Boot（Java/Kotlin） → springdoc-openapi（已完全替代老旧的 springfox）
- .NET 6/7/8/9 → Swashbuckle.AspNetCore
- Node.js/Express → swagger-jsdoc + swagger-ui-express
- NestJS → @nestjs/swagger
- Python FastAPI → 自带完美支持
- Go → swag 或 go-swagger
- 不依赖代码，想先设计接口 → 直接用 https://editor.swagger.io 写 yaml
经典访问地址（项目集成后）
- 文档页面：
http://localhost:8080/swagger-ui.html - 原始 OpenAPI 定义文件：
- JSON：
http://localhost:8080/v3/api-docs - YAML：
http://localhost:8080/v3/api-docs.yaml
一句话口号：
“写一次接口，文档、测试、SDK 全自动生成，永不同步是过去式。”
这就是 Swagger/OpenAPI 的全部本质。
后面你再深入学各种注解、springdoc、OpenAPI Generator 等，都是在这个基础上的延伸。
