Swagger 完全学习指南：从零到一搭建 API 文档自动化

Swagger 完全学习指南：从零到一搭建 API 文档自动化（附流程图与注解清单）

在前后端分离的开发模式下，API 文档的编写和维护一直是团队协作中的痛点——后端写完接口来不及更新文档，前端拿着过期的文档调半天调不通。Swagger 正是为了解决这个问题而诞生的。本文将系统讲解 Swagger 的核心概念、OpenAPI 规范、Spring Boot 集成、核心注解用法以及文档增强方案，帮助你彻底掌握 API 文档自动化的完整技术栈。

---

一、Swagger 是什么？

1.1 从 Swagger 到 OpenAPI

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。它的发展历程可以分为两个阶段：

• 2015 年前：Swagger 作为一套独立的技术规范，由 SmartBear 公司开发维护。
• 2017 年：Swagger 规范被捐献给 Linux 基金会，正式更名为 OpenAPI Specification（OAS） ，成为行业标准。而“Swagger”则继续作为品牌名称，用于指代基于该规范的工具生态系统。

简单来说：OpenAPI 是规范，Swagger 是实现这套规范的工具集合。OpenAPI 2.0 对应旧版的 Swagger 2.0，OpenAPI 3.0+ 是当前推荐使用的版本。

1.2 Swagger 的核心价值

Swagger 最大的价值是把接口文档和代码写在一起，通过注解自动生成文档页面。它带来的收益包括：

• 文档与代码同步：修改代码注解后，文档页面自动更新，彻底解决“接口改了文档没改”的问题。
• 交互式调试：前端可以直接在文档页面中填写参数并测试接口，无需额外工具。
• 多语言支持：通过 Swagger Codegen 可根据 OpenAPI 文档自动生成客户端 SDK 和服务器端 Stub。
• 标准化：OpenAPI 作为行业标准，被 Postman、Apifox 等主流工具广泛支持，可直接导入复用接口定义。

1.3 Swagger 工具链全景图

Swagger 工具链的核心组件包括：

• Swagger Editor：在线编辑器，支持实时编写和预览 OpenAPI 文档。
• Swagger UI：将 OpenAPI 文档渲染为可视化交互界面。
• Swagger Codegen：根据 OpenAPI 文档自动生成客户端 SDK 或服务端代码。
• Swagger Inspector：用于测试 API 并生成对应的 OpenAPI 定义。

---

二、OpenAPI 3.0 规范入门

2.1 什么是 OpenAPI 文档？

OpenAPI 文档是一个 YAML 或 JSON 文件，用于描述 RESTful API 的全部细节，包括：基本信息、服务器地址、路径与操作、参数与请求体、响应结构、数据模型定义等。建议优先使用 YAML 格式，以提升可读性与可维护性。

2.2 最小规范骨架

openapi: 3.0.0                           # 必填：OpenAPI 版本号
info:                                     # 必填：API 基本信息
  title: 示例 API
  version: 1.0.0
  description: API 文档规范示例
servers:                                  # 服务地址列表（替代 OAS 2.0 的 host/basePath）
  - url: http://localhost:8080/api/v1
    description: 本地开发环境
paths:                                    # 路径与操作
  /users:
    get:
      summary: 获取用户列表
      operationId: getUsers
      tags:
        - 用户
      parameters:
        - name: page
          in: query
          schema:
            type: integer
          description: 页码
      responses:
        '200':
          description: 成功返回用户列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:                               # 可复用组件（核心改进）
  schemas:
    User:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: 张三

2.3 OpenAPI 2.0 vs 3.0 核心差异

对于从旧项目迁移的开发者，了解版本差异很重要：

对比项	OpenAPI 2.0（Swagger 2.0）	OpenAPI 3.0+
根字段	swagger: "2.0"	openapi: 3.0.0
服务地址	host + basePath + schemes	servers 数组，支持多环境
数据模型	definitions	components/schemas
请求体	body 参数 + consumes	requestBody + content
响应	responses + produces	responses + content
示例	单个未命名示例	多命名示例，支持参数/头/请求体
可复用组件	有限	components（schemas/parameters/responses/examples）
JSON Schema	基于 draft-04	支持 draft-05，更灵活

新项目推荐直接使用 OpenAPI 3.0+，其结构更清晰、复用能力更强。

---

三、Spring Boot 集成 Swagger 3（完整实战）

3.1 技术选型：为什么选择 springdoc-openapi？

在 Spring Boot 中集成 Swagger 主要有两条技术路线：

• Springfox（旧方案） ：支持 Swagger 2，但已停止维护，与 Spring Boot 2.6+ 存在兼容性问题。
• springdoc-openapi（官方推荐） ：基于 OpenAPI 3 规范，支持 Spring Boot 2.x/3.x，天然兼容新版本。

本文采用 springdoc-openapi 方案，这也是当前社区的主流选择。

3.2 集成流程图

3.3 步骤一：添加依赖

以 Spring Boot 3.x 为例，在 pom.xml 中添加以下依赖：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.1.8</version>
</parent>

<dependencies>
    <!-- Spring Boot Web 依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- springdoc-openapi（包含 Swagger UI） -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.5.0</version>
    </dependency>
</dependencies>

注意：这个依赖项已包含 Swagger UI，无需额外引入其他依赖即可使用。

3.4 步骤二：配置文件

在 application.yml 中进行基础配置：

server:
  port: 8080

springdoc:
  api-docs:
    enabled: true                    # 开启 OpenAPI 文档接口
    path: /v3/api-docs              # JSON 文档路径，默认为 /v3/api-docs
  swagger-ui:
    enabled: true                   # 开启 Swagger UI 界面
    path: /swagger-ui/index.html    # UI 访问路径

3.5 步骤三：配置 Swagger 全局信息

创建配置类，设置 API 文档的基本元信息：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(new Info()
                .title("My API 文档")
                .description("Spring Boot 3 + Swagger 3 接口文档示例")
                .version("v1.0.0")
                .contact(new Contact()
                    .name("开发团队")
                    .email("dev@example.com")
                    .url("https://example.com"))
                .license(new License()
                    .name("Apache 2.0")
                    .url("https://www.apache.org/licenses/LICENSE-2.0")));
    }
}

3.6 步骤四：启动验证

启动 Spring Boot 应用后，访问以下地址即可查看 API 文档：

• Swagger UI 界面：http://localhost:8080/swagger-ui/index.html
• OpenAPI JSON 文档：http://localhost:8080/v3/api-docs

---

四、Swagger 3 核心注解详解

SpringDoc 基于 OpenAPI 3 规范，所有注解均位于 io.swagger.v3.oas.annotations 包及其子包中。以下按使用场景分类说明。

4.1 注解体系图谱

4.2 类级别注解

@Tag：描述 Controller 模块

用于定义 Controller 的功能分组，替代 Swagger 2 的 @Api。

import io.swagger.v3.oas.annotations.tags.Tag;

@Tag(name = "用户管理", description = "用户增删改查接口", order = 1)
@RestController
@RequestMapping("/users")
public class UserController {
    // ...
}

属性	类型	说明
name	String	模块名称（必填）
description	String	模块功能说明
order	int	排序序号，数字越小越靠前

4.3 方法级别注解

@Operation：描述接口功能

替代 Swagger 2 的 @ApiOperation。

import io.swagger.v3.oas.annotations.Operation;

@Operation(summary = "根据ID查询用户", description = "返回用户详细信息及关联角色")
@GetMapping("/{id}")
public Result<UserVO> getUserById(@PathVariable Long id) {
    // ...
}

属性	类型	说明
summary	String	接口简短名称（必填）
description	String	接口详细说明
hidden	boolean	是否隐藏该接口

@Hidden：隐藏接口

语义更清晰的隐藏方式，可直接标注在类或方法上。

@Hidden  // 该接口不在文档中显示
@GetMapping("/internal")
public Result<String> internalApi() {
    // ...
}

@ApiResponses / @ApiResponse：描述响应状态码

import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@Operation(summary = "创建用户")
@PostMapping
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "创建成功"),
    @ApiResponse(responseCode = "400", description = "参数错误"),
    @ApiResponse(responseCode = "409", description = "用户已存在")
})
public Result<Long> createUser(@RequestBody UserCreateDTO dto) {
    // ...
}

4.4 参数级别注解

@Parameter：描述单个参数

适用于 @PathVariable、@RequestParam、@RequestHeader。

@GetMapping("/list")
public Result<List<UserVO>> listUsers(
    @Parameter(name = "pageNum", description = "页码", required = true, example = "1")
    @RequestParam Integer pageNum,
    
    @Parameter(name = "pageSize", description = "每页条数", example = "20")
    @RequestParam(defaultValue = "20") Integer pageSize,
    
    @Parameter(name = "Authorization", description = "认证令牌", required = true)
    @RequestHeader String authorization
) {
    // ...
}

属性	说明
name	参数名称
description	参数说明
required	是否必填
example	示例值
hidden	是否隐藏

@RequestBody：描述 JSON 请求体

@PostMapping("/add")
public Result<Boolean> addUser(
    @RequestBody(description = "新增用户参数，用户名/密码为必填")
    UserAddDTO dto
) {
    // ...
}

@ParameterObject：封装多参数

当方法参数较多时，可以将多个 @RequestParam 封装为一个对象。

@Data
public class UserQueryDTO {
    private String name;
    private Integer age;
    private Integer pageNum = 1;
    private Integer pageSize = 10;
}

@GetMapping("/page")
public Result<Page<UserVO>> pageUsers(
    @ParameterObject(description = "用户分页查询参数")
    UserQueryDTO queryDTO
) {
    // ...
}

4.5 数据模型注解

@Schema：描述实体类字段

替代 Swagger 2 的 @ApiModel 和 @ApiModelProperty。

import io.swagger.v3.oas.annotations.media.Schema;

@Data
@Schema(description = "用户信息实体")
public class UserVO {
    
    @Schema(description = "用户ID", example = "1001", required = true)
    private Long id;
    
    @Schema(description = "用户名", example = "张三", minLength = 2, maxLength = 20)
    private String name;
    
    @Schema(description = "邮箱", format = "email", example = "zhangsan@example.com")
    private String email;
    
    @Schema(description = "年龄", minimum = "0", maximum = "150", example = "25")
    private Integer age;
    
    @Schema(description = "用户状态", allowableValues = {"active", "inactive"}, example = "active")
    private String status;
}

属性	说明
description	字段说明
example	示例值
required	是否必填
minLength / maxLength	字符串长度限制
minimum / maximum	数值范围限制
format	格式约束（如 email、date-time）
allowableValues	允许的值列表

4.6 注解使用流程总结

---

五、文档增强：Knife4j 让文档更漂亮

5.1 为什么需要 Knife4j？

Swagger UI 默认界面比较简陋，不够美观和易用。Knife4j 是一款基于 Swagger 的增强工具，能让接口文档变得更漂亮，还能增加分组显示、接口调试等实用功能。

5.2 快速集成 Knife4j

步骤一：替换依赖

移除 springdoc-openapi-starter-webmvc-ui，添加 Knife4j 依赖：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.5.0</version>
</dependency>

若使用 Spring Boot 2.x（非 Jakarta），使用 knife4j-openapi3-spring-boot-starter。

步骤二：保持配置不变

Knife4j 完全兼容 SpringDoc 的配置和注解，原有配置无需修改。

步骤三：访问新界面

启动项目后访问：http://localhost:8080/doc.html

5.3 Swagger UI vs Knife4j 对比

特性	Swagger UI	Knife4j
界面美观度	简约基础	现代化设计，功能丰富
接口调试	基础支持	增强调试体验
接口分组	基础分组	多层级分组
离线文档导出	不支持	支持 Markdown/Word
全局参数配置	需手写代码	界面化配置
个性化配置	有限	丰富

---

六、生产环境高级配置

6.1 生产环境关闭 Swagger

Swagger UI 不应在生产环境暴露。可通过配置文件和条件注解控制：

springdoc:
  api-docs:
    enabled: false   # 生产环境关闭
  swagger-ui:
    enabled: false   # 生产环境关闭

或通过 Profile 控制：

@Configuration
@Profile({"dev", "test"})  // 仅在开发/测试环境生效
public class SwaggerConfig {
    // ...
}

6.2 API 分组配置

当项目有多个模块时，可以配置分组管理：

@Bean
public GroupedOpenApi userApi() {
    return GroupedOpenApi.builder()
        .group("用户管理")
        .pathsToMatch("/users/**")
        .packagesToScan("com.example.user")
        .build();
}

@Bean
public GroupedOpenApi orderApi() {
    return GroupedOpenApi.builder()
        .group("订单管理")
        .pathsToMatch("/orders/**")
        .packagesToScan("com.example.order")
        .build();
}

6.3 全局参数配置（如 Token）

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
        .components(new Components()
            .addSecuritySchemes("bearerAuth",
                new SecurityScheme()
                    .type(SecurityScheme.Type.HTTP)
                    .scheme("bearer")
                    .bearerFormat("JWT")));
}

---

七、Swagger 与其他 API 工具的对比

在实际开发中，你可能还需要了解 Swagger 与其他主流工具的定位差异：

工具	核心定位	适用场景
Swagger	API 文档标准化与自动生成	注重规范管理、前后端分离项目
Postman	API 测试为核心	日常接口调试、团队测试协作
Apifox	一体化平台（设计+调试+测试+MOCK）	追求一体化、多工具协同的团队

值得一提的是，Postman 和 Apifox 均支持直接导入 Swagger/OpenAPI 文档地址或文件，复用接口定义进行测试，便于团队共享用例与规范统一。

---

八、常见问题与解决方案

问题 1：访问 Swagger UI 显示 404

原因：依赖缺失或路径配置错误。
解决方案：确保引入 springdoc-openapi-starter-webmvc-ui 依赖，而非仅引入 springdoc-openapi-webmvc-core。访问路径应为 /swagger-ui/index.html（而非 /swagger-ui.html）。

问题 2：接口在文档中不显示

原因：Controller 未被扫描到，或被 @Hidden 隐藏。
解决方案：检查包扫描路径配置，确保 Controller 类上无 @Hidden，接口方法上无 hidden = true。

问题 3：Spring Boot 2.6+ 与旧版 Springfox 冲突

原因：Spring Boot 2.6+ 默认禁用 bean 覆盖，而 Springfox 和 SpringDoc 会注册同名 bean。
解决方案：放弃 Springfox，迁移到 SpringDoc。

问题 4：实体类字段说明不显示

原因：使用了错误的注解包。
解决方案：OpenAPI 3 使用 @Schema（io.swagger.v3.oas.annotations.media.Schema），而非 Swagger 2 的 @ApiModelProperty（io.swagger.annotations.ApiModelProperty）。

---

九、总结

本文从 Swagger 的历史演进讲起，系统地介绍了：

1. 核心概念：OpenAPI 是规范，Swagger 是实现工具，新项目推荐 OpenAPI 3.0+。
2. 规范入门：OpenAPI 文档结构与 YAML 骨架，以及 2.0 与 3.0 的核心差异。
3. Spring Boot 集成：使用 springdoc-openapi 完整集成 Swagger UI 的全流程（附流程图）。
4. 注解体系：从 @Tag 到 @Schema 的全套注解详解（附注解图谱）。
5. 文档增强：Knife4j 让 API 文档更美观、功能更强大。
6. 生产配置：环境隔离、API 分组、全局参数等高级功能。
7. 工具对比：Swagger 与其他 API 工具的定位差异与协同使用。

推荐学习路线：

1. ✅ 阅读本文，掌握 Swagger 3.0 核心用法
2. 🔧 在个人项目中实践 springdoc-openapi 集成
3. 🎨 引入 Knife4j 美化文档界面
4. 🚀 学习 OpenAPI 规范深度定制
5. 🔗 结合 CI/CD 实现文档自动部署

---

📌 配套代码：文中所有代码示例已整理为 Spring Boot 完整项目，可访问 GitHub - swagger-demo 获取（示例链接）。