介绍
围绕 OpenAPI规范 开发的一套开源工具集（品牌名称），不是规范本身。
- OpenAPI = API标准文档格式（蓝图）
- Swagger = 操作这份蓝图的全套工具
日常开发大家口中的「接入Swagger」，绝大多数指 Swagger UI（交互式接口文档页面）。
工具组件
1. Swagger UI（使用最多）
- 功能：读取OpenAPI规范文件，生成可视化交互式网页文档
- 核心能力：
- 展示所有接口、请求方式、路径、入参、返回模型、状态码
- Try it out：网页直接发起HTTP请求，在线调试接口（简易版Postman）
- 访问地址（OpenAPI3）：
http://localhost:8080/swagger-ui/index.html
2. Swagger Editor
浏览器在线编辑器，编写、预览、校验OpenAPI yaml/json；支持实时预览文档，适合先定义接口，再写代码（设计优先）。
官网：editor.swagger.io
3. Swagger Codegen
根据OpenAPI规范自动生成代码：
- 服务端骨架代码（Java/Go/Python等）
- 前端客户端SDK、请求类
适合标准契约驱动开发。
4. Swagger Core
Java库，用于解析、生成OpenAPI规范文件（SpringDoc底层依赖）
开发模式
模式1：Code First（代码优先，国内最常用）
流程： 编写后端接口代码 → 添加注解 → 框架自动扫描代码生成OpenAPI规范 → SwaggerUI渲染文档
例子：
- SpringBoot + SpringDoc
- Node.js + swagger-jsdoc
- FastAPI 内置 OpenAPI 支持，自带 Swagger UI 页面
优点： 开发习惯贴合后端；
缺点：注解侵入业务代码。
模式2：Design First（设计优先/契约优先）
流程： 先用 Swagger Editor 编写OpenAPI规范 → 根据规范生成前后端代码 → 开发实现
优点： 前后端提前对齐接口契约，适合大型团队、微服务；缺点：前期学习成本高。
作用
- 告别手动维护接口文档：代码改动，文档自动同步，杜绝「文档和代码不一致」
- 前后端协作利器：前端直接打开页面查看参数、调试接口，减少大量沟通成本
- 自带在线调试，简单接口不用打开Postman
- 标准化API描述，所有项目接口文档格式统一
- 可导出OpenAPI文件导入 Apifox、Postman、自动化测试工具
优点 & 缺点
优点
- 自动化文档，减少维护成本
- 开箱即用，主流框架都有成熟集成方案
- 交互式在线调试
- 标准OpenAPI格式，可以和绝大多数API工具互通
- 跨语言支持：Java/Python/Node/.NET/Go全部支持
缺点
- 代码优先模式下注解侵入业务代码
- 安全风险：生产环境如果开放访问，会暴露全部接口信息
- 仅原生支持RESTful HTTP接口；gRPC、Dubbo、WebSocket支持较差
- 复杂嵌套对象、复杂业务场景文档可读性一般
- 如果开发人员不规范写注解，文档会残缺无用
适用场景 & 不适用场景
适合
- 前后端分离RESTful项目
- 微服务多团队协作
- 接口迭代频繁，需要持续维护文档
- 需要对外提供开放API
不适合
- 非REST接口（Dubbo、gRPC为主系统）
- 极高安全保密系统（不想暴露任何接口信息）
- 完全不允许代码添加任何注解的项目
软件区分
- Swagger：基于OpenAPI规范，自动生成文档，偏向「文档+契约」
- Postman：接口调试工具，以手动创建接口集合为主
- Apifox：一体化平台，可以导入OpenAPI规范，集成文档、调试、Mock、自动化测试
行业通用搭配：后端使用SpringDoc生成OpenAPI → Apifox导入规范统一管理接口。