Swagger：基于 OpenAPI 规范的接口文档生成与在线调试工具-马育民老师

# 介绍

**围绕 [OpenAPI规范](https://www.malaoshi.top/show_1GW3n3vSgjUN.html "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规范 → 根据规范生成前后端代码 → 开发实现

**优点：** 前后端提前对齐接口契约，适合大型团队、微服务；缺点：前期学习成本高。

# 作用

1. **告别手动维护接口文档**：代码改动，文档自动同步，杜绝「文档和代码不一致」
2. **前后端协作利器**：前端直接打开页面查看参数、调试接口，减少大量沟通成本
3. **自带在线调试**，简单接口不用打开Postman
4. **标准化API描述**，所有项目接口文档格式统一
5. 可导出OpenAPI文件导入 Apifox、Postman、自动化测试工具

# 优点 & 缺点
### 优点
1. 自动化文档，减少维护成本
2. 开箱即用，主流框架都有成熟集成方案
3. 交互式在线调试
4. 标准OpenAPI格式，可以和绝大多数API工具互通
5. 跨语言支持：Java/Python/Node/.NET/Go全部支持

### 缺点
1. **代码优先模式下注解侵入业务代码**
2. **安全风险：生产环境如果开放访问，会暴露全部接口信息**
3. 仅原生支持RESTful HTTP接口；gRPC、Dubbo、WebSocket支持较差
4. 复杂嵌套对象、复杂业务场景文档可读性一般
5. 如果开发人员不规范写注解，文档会残缺无用

# 适用场景 & 不适用场景

### **适合**

- 前后端分离RESTful项目
- 微服务多团队协作
- 接口迭代频繁，需要持续维护文档
- 需要对外提供开放API

### **不适合**

- 非REST接口（Dubbo、gRPC为主系统）
- 极高安全保密系统（不想暴露任何接口信息）
- 完全不允许代码添加任何注解的项目

# 软件区分

1. **Swagger**：基于OpenAPI规范，**自动生成文档**，偏向「文档+契约」
2. **Postman**：接口调试工具，以手动创建接口集合为主
3. **Apifox**：一体化平台，可以**导入OpenAPI规范**，集成文档、调试、Mock、自动化测试

行业通用搭配：后端使用SpringDoc生成OpenAPI → Apifox导入规范统一管理接口。

原文出处：/show_1GW3n3uHkF2M.html