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 工具链全景图

SpringBoot集成
Swagger工具链
规范定义
OpenAPI Specification

YAML/JSON 格式
Swagger Editor

在线编辑器
Swagger UI

可视化文档界面
Swagger Codegen

代码生成器
Swagger Inspector

API测试工具
springdoc-openapi

自动生成 OpenAPI 文档
Knife4j

增强版 UI
前端/测试人员

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 最小规范骨架

yaml 复制代码

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 集成流程图

是
否
开始集成
在 pom.xml 中添加

springdoc-openapi-starter-webmvc-ui 依赖
配置 application.yml

启用 api-docs 和 swagger-ui
创建 SwaggerConfig 配置类

设置 OpenAPI 元信息
在 Controller 和实体类

添加 Swagger3 注解
启动 Spring Boot 应用
访问 /swagger-ui/index.html
文档正常显示？
集成完成
检查依赖版本

端口/路径配置

3.3 步骤一：添加依赖

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

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 中进行基础配置：

yaml 复制代码

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 文档的基本元信息：

java 复制代码

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 注解体系图谱

数据模型
参数级别
方法级别
类级别
@Tag

描述 Controller 模块
@Operation

描述单个接口功能
@Hidden

隐藏接口
@ApiResponses

组合响应状态码
@ApiResponse

单个响应状态码
@Parameter

描述路径/查询/头参数
@RequestBody

描述 JSON 请求体
@ParameterObject

封装多参数为对象
@Schema

描述实体类字段

4.2 类级别注解

@Tag：描述 Controller 模块

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

java 复制代码

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。

java 复制代码

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：隐藏接口

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

java 复制代码

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

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

java 复制代码

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。

java 复制代码

@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 请求体

java 复制代码

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

@ParameterObject：封装多参数

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

java 复制代码

@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。

java 复制代码

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 注解使用流程总结

实体类
Controller 类
@Tag

模块分组
接口方法

@Operation 描述
路径/查询/头参数

@Parameter
请求体

@RequestBody
响应状态码

@ApiResponses
字段

@Schema

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

5.1 为什么需要 Knife4j？

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

5.2 快速集成 Knife4j

步骤一：替换依赖

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

xml 复制代码

<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 不应在生产环境暴露。可通过配置文件和条件注解控制：

yaml 复制代码

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

或通过 Profile 控制：

java 复制代码

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

6.2 API 分组配置

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

java 复制代码

@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）

java 复制代码

@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 的历史演进讲起，系统地介绍了：

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

推荐学习路线：

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

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