Spring Boot整合Swagger 3.0:自动生成API文档并在线调试

麦兜*2026-01-13 8:19

Spring Boot整合Swagger 3.0:自动生成API文档并在线调试

    • 一、整体流程与原理概览（先看全貌）
    • [我们接下来要做的事，就是在 Spring Boot 项目中引入 springdoc-openapi 相关依赖，并用注解 + 配置来控制 A→D 的过程，从而让 E+F 能自动工作。](#我们接下来要做的事，就是在 Spring Boot 项目中引入 springdoc-openapi 相关依赖，并用注解 + 配置来控制 A→D 的过程，从而让 E+F 能自动工作。)
    • 二、前置准备：环境与版本选择说明
    • 三、快速上手：引入依赖与启动验证
    • [四、自定义 OpenAPI 信息：标题、版本、联系方式等](#四、自定义 OpenAPI 信息：标题、版本、联系方式等)
    • [然后在 OpenAPI Bean 里通过 @Value 注入使用。](#然后在 OpenAPI Bean 里通过 @Value 注入使用。)
    • [五、接口文档注解详解（Swagger 3.0）](#五、接口文档注解详解（Swagger 3.0）)
    • [在 Swagger UI 中，这个接口会展示 200、404 两种情况的说明。](#在 Swagger UI 中，这个接口会展示 200、404 两种情况的说明。)
    • [六、启动后如何使用 Swagger UI 在线调试](#六、启动后如何使用 Swagger UI 在线调试)
    • [七、API 文档分组与多模块管理](#七、API 文档分组与多模块管理)
    • 八、整体流程图：从项目启动到在线调试
    • 九、生产环境安全与部署注意事项
    • 十、常见问题与坑点排查
    • [十一、一个小示例：从 0 到 1 的完整 Demo](#十一、一个小示例：从 0 到 1 的完整 Demo)
    • 总结

一、整体流程与原理概览（先看全貌）

"Swagger 3.0"在 Spring Boot 生态里，现在更推荐的做法是使用 springdoc-openapi 来生成 OpenAPI 3 文档，并自动集成 Swagger UI 页面。它可以通过扫描 Controller、注解，自动暴露：

  • /swagger-ui.html（Swagger UI 可视化调试页面）
  • /v3/api-docs（机器可读的 OpenAPI 3 JSON 描述）

我们接下来要做的事，就是在 Spring Boot 项目中引入 springdoc-openapi 相关依赖，并用注解 + 配置来控制 A→D 的过程，从而让 E+F 能自动工作。

二、前置准备：环境与版本选择说明

在开始之前，先确认两个关键点：

  1. Spring Boot 版本与 springdoc-openapi 版本
  • Spring Boot 3.x（Jakarta EE 9+ 包名从 javax.* 变为 jakarta.*）：
    • 使用 springdoc-openapi v2 系列，依赖为：
      • springdoc-openapi-starter-webmvc-ui（Spring MVC）
  • Spring Boot 2.x（javax.* 命名空间）：
    • 使用 springdoc-openapi v1 系列，依赖为：
      • springdoc-openapi-ui（老名字，功能类似）
        下面示例以"Spring Boot 3.x + springdoc-openapi v2"为主；如果你是 2.x，把依赖名字和部分写法微调即可。
  1. 项目类型
  • 标准的 Spring Web MVC 项目（@RestController）
  • 如果是 WebFlux（Reactive），则要使用 webflux-ui 的 starter，本篇以 Web MVC 为主。

三、快速上手：引入依赖与启动验证

  1. Maven 依赖示例（Spring Boot 3.x）
    在 pom.xml 中添加依赖（版本号可随 Boot 版本自动管理，也可显式指定）：
xml 复制代码 
<dependencies>
    <!-- 其他已有依赖... -->
    <!-- SpringDoc OpenAPI 3 (Swagger UI) starter for Spring MVC -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <!-- 可不写 version，让 Spring Boot 管理 -->
        <version>2.3.0</version> <!-- 示例版本，请按当前最新稳定版选择 -->
    </dependency>
</dependencies>

如果你是 Spring Boot 2.x，则使用：

xml 复制代码 
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.8.0</version>
</dependency>

版本号可以参考 springdoc 官方文档与 Release 说明。

  1. application.yml 基础配置（可选）

即使不做任何配置，启动项目后通常也能直接用默认设置访问 Swagger UI。但一般我们会至少加几项基础配置：

yaml 复制代码 
springdoc:
  api-docs:
    # OpenAPI 描述的访问路径
    path: /v3/api-docs
  swagger-ui:
    # Swagger UI 访问路径
    path: /swagger-ui.html
    # 默认展开所有标签页（可选）
    default-models-expand-depth: 1
    default-model-expand-depth: 1
  # 打包的 Controller 扫描基础包（可选）
  packages-to-scan: com.example.demo.controller
  # 也可以按路径前缀过滤
  paths-to-match: /api/**
  1. 写一个最简单的 Controller
java 复制代码 
package com.example.demo.controller;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@Tag(name = "Demo", description = "示例接口")
@RestController
public class DemoController {
    @Operation(summary = "打招呼", description = "根据名字返回打招呼消息")
    @GetMapping("/hello")
    public String hello(@RequestParam("name") String name) {
        return "Hello, " + name;
    }
}
  1. 启动项目并访问

四、自定义 OpenAPI 信息：标题、版本、联系方式等

为了让文档看起来更"专业"，一般会定义一个配置类，注入 OpenAPI Bean。springdoc-openapi 会在 Spring 上下文中寻找这个 Bean 来组装全局文档信息。

  1. 创建 OpenApiConfig 配置类
java 复制代码 
package com.example.demo.config;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("示例系统 API 文档")
                        .version("1.0.0")
                        .description("基于 Spring Boot + SpringDoc 的示例 REST API 文档，支持在线调试。")
                        .contact(new Contact()
                                .name("示例团队")
                                .email("support@example.com")
                                .url("https://example.com"))
                        .license(new License()
                                .name("Apache 2.0")
                                .url("https://www.apache.org/licenses/LICENSE-2.0.html")));
    }
}

重启项目后，Swagger UI 首页顶部会显示你在 Info 中配置的标题、版本、描述、联系方式等信息。

  1. 外部化配置（可选）

你也可以把部分信息提到配置文件里，方便多环境管理：

yaml 复制代码 
springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
app:
  api:
    title: 示例系统 API 文档
    version: @project.version@
    description: 示例系统 API 描述...

然后在 OpenAPI Bean 里通过 @Value 注入使用。

五、接口文档注解详解（Swagger 3.0）

Swagger 3 使用 io.swagger.v3.oas.annotations 包下的一系列注解来补充文档信息。以下是最常用的几种：

  1. 类级别注解
  • @Tag
    • 用在 Controller 类上，描述一组接口的分组与说明。
    • 常用属性：
      • name：标签名
      • description：描述
        示例：
java 复制代码 
@Tag(name = "用户管理", description = "用户注册、登录、信息修改等接口")
@RestController
@RequestMapping("/users")
public class UserController {
    // ...
}
  1. 方法级别注解
  • @Operation
    • 用在接口方法上，描述具体一个接口的功能。
    • 常用属性：
      • summary：简短标题
      • description：详细描述
      • tags：如果不使用类上的 @Tag，也可以通过这里指定。
        示例：
java 复制代码 
@Operation(summary = "用户注册", description = "通过用户名与密码创建新用户")
@PostMapping("/register")
public UserDTO register(@RequestBody RegisterRequest req) {
    // ...
}
  • @Parameter
    • 用来描述方法参数（@RequestParam、@PathVariable 等）。
    • 可以指定：
      • name：参数名
      • description：说明
      • required：是否必填
      • example：示例值
        示例：
java 复制代码 
@GetMapping("/{id}")
public UserDTO getById(
        @Parameter(description = "用户 ID", required = true, example = "1")
        @PathVariable("id") Long id) {
    // ...
}
  • @RequestBody（非 Swagger 注解，但与文档相关）
    • 配合 @Schema 使用，可以更精细描述请求体字段。
      示例：
java 复制代码 
@Operation(summary = "创建用户")
@PostMapping
public UserDTO create(
        @io.swagger.v3.oas.annotations.parameters.RequestBody(
                description = "用户创建信息",
                required = true,
                content = @Content(
                        schema = @Schema(implementation = UserCreateRequest.class)
                )
        )
        @RequestBody UserCreateRequest request) {
    // ...
}
  1. DTO / 实体类字段注解
  • @Schema
    • 用于类或字段，描述数据结构、示例、枚举等。
      示例：
java 复制代码 
@Schema(description = "用户创建请求")
public class UserCreateRequest {
    @Schema(description = "用户名", example = "zhangsan", required = true)
    private String username;
    @Schema(description = "密码", example = "passw0rd", required = true)
    private String password;
}

Swagger UI 会根据这些注解生成参数说明和示例值，让前端/测试一看就懂。

  1. 响应描述
  • @ApiResponses 和 @ApiResponse
    • 用来描述不同 HTTP 状态码对应的响应情况。
    • 常用属性：
      • responseCode：状态码（如 "200", "400", "404"）
      • description：描述
      • content：响应体结构与示例
        示例：
java 复制代码 
@Operation(summary = "根据 ID 查用户")
@ApiResponses({
        @ApiResponse(responseCode = "200", description = "成功",
                content = @Content(schema = @Schema(implementation = UserDTO.class))),
        @ApiResponse(responseCode = "404", description = "用户不存在",
                content = @Content)
})
@GetMapping("/{id}")
public UserDTO getById(@PathVariable Long id) {
    // ...
}

在 Swagger UI 中，这个接口会展示 200、404 两种情况的说明。

六、启动后如何使用 Swagger UI 在线调试

  1. 打开 Swagger UI 页面
    启动 Spring Boot 应用后访问：
  1. 查看接口详情
  • 点击某个 Tag（如"用户管理"），展开其中的接口（如 POST /users）。
  • 右侧会显示：
    • 请求方法（POST/GET/PUT/DELETE...）
    • 请求路径
    • 请求参数（Query、Path、Header、Body）
    • 响应示例（根据 @Schema 和 @ApiResponse 生成）
  1. 在线调试（"Try it out"）
  • 点击右侧区域的 "Try it out" 按钮：
    • 参数变为可编辑状态。
  • 根据文档填入参数：
    • Query 参数：直接输入框填写。
    • Body：如果是 JSON 请求体会给出模板，可以直接修改字段值。
  • 点击 "Execute"：
    • 浏览器会向你的后端发送一个真实 HTTP 请求。
    • 下方的 Response body、status code、headers 会显示返回结果。
      这个"在线调试"能力对前后端联调、QA 自测非常有用，避免了手写 cURL 或 Postman 请求。

七、API 文档分组与多模块管理

如果你的系统有很多模块/微服务，你可能希望把接口按不同的"组"展示，而不是一大坨堆在一起。这可以通过 GroupedOpenApi Bean 来实现。

  1. 定义多个 GroupedOpenApi
java 复制代码 
package com.example.demo.config;
import io.swagger.v3.oas.models.OpenAPI;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        // 同上，略
        return new OpenAPI()
                .info(new Info()
                        .title("示例系统 API 文档")
                        .version("1.0.0")
                        .description("支持在线调试的 API 文档"));
    }
    // 分组1：用户相关接口
    @Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
                .group("user")
                .pathsToMatch("/users/**")
                .build();
    }
    // 分组2：订单相关接口
    @Bean
    public GroupedOpenApi orderApi() {
        return GroupedOpenApi.builder()
                .group("order")
                .pathsToMatch("/orders/**")
                .build();
    }
}
  1. Swagger UI 中的效果
  • Swagger UI 右上角会多出一个"Select a spec"下拉框，可以选择 "user" / "order" 等分组。
  • 每个分组下只展示匹配的接口，便于多人协作、不同团队查看各自的 API。
    也可以基于包名进行分组：
java 复制代码 
@Bean
public GroupedOpenApi apiV1() {
    return GroupedOpenApi.builder()
            .group("api-v1")
            .packagesToScan("com.example.demo.controller.v1")
            .build();
}

八、整体流程图：从项目启动到在线调试

为了更直观，用一个流程图串起我们前面做的事情：
渲染错误: Mermaid 渲染失败: Parse error on line 4: ... + Swagger 3 注解
(@Tag, @Operation, @ -----------------------^ Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', 'STADIUMEND', 'SUBROUTINEEND', 'PIPE', 'CYLINDEREND', 'DIAMOND_STOP', 'TAGEND', 'TRAPEND', 'INVTRAPEND', 'UNICODE_TEXT', 'TEXT', 'TAGSTART', got 'PS'

九、生产环境安全与部署注意事项

  1. 不要在生产环境暴露 Swagger UI
  • Swagger UI 对内非常方便，但对公开的互联网服务来说，可能泄露接口结构、甚至允许被恶意调用。
  • 常见做法：
    • 只在 dev / test 环境启用；
    • 在生产环境关闭 swagger-ui 端点或通过安全控制限制访问。
  1. 按环境控制是否启用 Swagger
    方式一：使用 @Profile
java 复制代码 
@Configuration
@Profile({"dev", "test"}) // 仅 dev/test 环境加载这个配置
public class OpenApiConfig {
    // ...
}

方式二：配置开关（更灵活）

yaml 复制代码 
springdoc:
  api-docs:
    enabled: ${springdoc.enabled:true}
  swagger-ui:
    enabled: ${springdoc.enabled:true}

在生产环境启动时设置 springdoc.enabled=false，即关闭 OpenAPI 与 Swagger UI。

  1. 与 Spring Security 结合访问控制

如果项目已经使用 Spring Security，可以通过配置限制 /swagger-ui.html 和 /v3/api-docs 只允许内部 IP 或认证用户访问：

java 复制代码 
@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth
                        .requestMatchers("/swagger-ui.html",
                                "/swagger-ui/**",
                                "/v3/api-docs/**",
                                "/swagger-resources/**")
                        .hasRole("DEVELOPER") // 或 permitAll() 但配合网关控制
                        .anyRequest().authenticated()
                )
                // ...
        return http.build();
    }
}

十、常见问题与坑点排查

  1. 访问 /swagger-ui.html 404
  • 检查依赖是否正确引入（尤其是 Boot 3.x 必须用 webmvc-ui 的 starter）。
  • 确认没有在 Security / Filter 中误拦截该路径。
  • 检查是否设置了错误的 springdoc.swagger-ui.path。
  1. 没有扫描到我的接口
  • 检查 springdoc.packages-to-scan / paths-to-match 配置是否把你的 Controller 排除在外。
  • 确保 Controller 类上有 @RestController（或 @Controller + @ResponseBody）以及正确的 @RequestMapping 路径。
  1. 参数文档缺失、类型识别不对
  • 常见原因：
    • 没有加 @Parameter 或 @Schema，只有基础类型；
    • 使用了包装类型（如 ResponseEntity）但没有告知泛型类型。
  • 解决：
    • 在方法参数上加 @Parameter 注解；
    • 在 DTO 上加 @Schema(description = "xxx")；
    • 对复杂返回类型可以用 @Operation 的响应部分显式声明 schema。
  1. 在 Spring Boot 3 下仍然使用 springdoc-openapi-ui
  • Boot 3.x 应该使用 springdoc-openapi-starter-webmvc-ui，否则可能出现类找不到、包名不匹配问题。
  1. 多 OpenAPI Definition 没有分组选择框
  • 需要定义 GroupedOpenApi Bean，springdoc 才会生成多个"组"，并在 Swagger UI 中显示下拉选择框。

十一、一个小示例：从 0 到 1 的完整 Demo

下面是一个最小可用示例，便于你直接复制试验（以 Spring Boot 3.x + Maven 为例）：

  1. pom.xml 关键部分
xml 复制代码 
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.0</version>
</parent>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.3.0</version>
    </dependency>
</dependencies>
  1. application.yml
yaml 复制代码 
spring:
  application:
    name: demo-swagger3
springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
  packages-to-scan: com.example.demo.controller
  1. OpenApiConfig
java 复制代码 
package com.example.demo.config;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Demo API")
                        .version("1.0.0")
                        .description("Spring Boot + SpringDoc 示例 API")
                        .contact(new Contact()
                                .name("Me")
                                .email("me@example.com")));
    }
}
  1. DemoController
java 复制代码 
package com.example.demo.controller;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;
@Tag(name = "Demo", description = "示例接口")
@RestController
@RequestMapping("/demo")
public class DemoController {
    @Operation(summary = "打招呼接口")
    @GetMapping("/hello")
    public String hello(
            @Parameter(description = "名字", example = "world")
            @RequestParam(defaultValue = "world") String name) {
        return "Hello, " + name;
    }
    @Operation(summary = "Echo 接口")
    @PostMapping("/echo")
    public String echo(@RequestBody String body) {
        return body;
    }
}
  1. 启动与验证
  • 运行 main 方法启动 Boot 应用。
  • 访问：
  • 在页面中：
    • 展开标签 "Demo"；
    • 点击 GET /demo/hello 的 "Try it out"，输入 name，执行；
    • 点击 POST /demo/echo 的 "Try it out"，在 Body 中输入一段文本，执行；
    • 查看响应结果。
      如果你能看到请求正常发出并收到返回，就说明你已经成功完成了"Spring Boot 整合 Swagger 3.0：自动生成 API 文档并在线调试"的目标。

总结

  • 在 Spring Boot 中整合 Swagger 3.0，现在推荐使用 springdoc-openapi：
    • Boot 3.x 使用 springdoc-openapi-starter-webmvc-ui
    • Boot 2.x 使用 springdoc-openapi-ui
  • 核心步骤：
    1. 引入依赖
    2. 配置 OpenAPI Bean（全局信息）
    3. 在 Controller / DTO 上加 Swagger 3 注解
    4. 启动后访问 /swagger-ui.html 进行在线调试
  • 对于复杂项目，使用 GroupedOpenApi 完成接口分组，更易于维护与使用。
  • 生产环境务必注意安全：按环境控制启用、配合 Spring Security 限制访问范围。
  • 遇到问题时，重点检查依赖版本、路径配置、安全规则和注解使用是否符合 Swagger 3 规范。
    按照本文步骤，你就可以在自己的 Spring Boot 项目中快速搭建一套"自动生成 API 文档 + 在线调试"的 Swagger 3.0 环境，大幅提升前后端协作与接口自测效率。
相关推荐
接着奏乐接着舞。2 小时前
Go 一小时上手指南：从零到运行第一个程序
开发语言·后端·golang
星火开发设计2 小时前
C++ deque 全面解析与实战指南
java·开发语言·数据结构·c++·学习·知识
河码匠2 小时前
Django rest framework 自定义url
后端·python·django
独自破碎E2 小时前
什么是RabbitMQ中的死信队列？
java·rabbitmq·java-rabbitmq
码界奇点2 小时前
基于Spring与Netty的分布式配置管理系统设计与实现
java·分布式·spring·毕业设计·源代码管理
计算机毕设指导62 小时前
基于微信小程序的咖啡店点餐系统【源码文末联系】
java·spring boot·微信小程序·小程序·tomcat·maven·intellij-idea
Geoking.2 小时前
【设计模式】外观模式（Facade）详解
java·设计模式·外观模式
JaguarJack2 小时前
2026 年 PHP 8.4 依然重要：跳到 8.5 之前你该掌握的特性
后端·php·服务端
程序员爱钓鱼2 小时前
Node.js 博客系统实战（一）：项目需求分析
前端·后端·node.js
热门推荐
01GitHub 镜像站点02Labelme从安装到标注：零基础完整指南03网站改了域名，如何查找？04安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）05Linux下V2Ray安装配置指南06【踩坑笔记】50系显卡适配的 PyTorch 安装07Claude Code 2.1.2 升级报错？别折腾了，一行命令搞定082025-04-03 Latex学习1——本地配置Latex + VScode环境09KGG转MP3工具|非KGM文件|解密音频10jdk21下载、安装（Windows、Linux、macOS）