你还在手写 Swagger 文档？SpringDoc 自动生成不香吗？

🏆本文收录于《滚雪球学SpringBoot 3》:https://blog.csdn.net/weixin_43970743/category_12795608.html，专门攻坚指数提升，本年度国内最系统+最专业+最详细（永久更新）。
  
本专栏致力打造最硬核 SpringBoot3 从零基础到进阶系列学习内容，🚀均为全网独家首发，打造精品专栏，专栏持续更新中…欢迎大家订阅持续学习。 如果想快速定位学习，可以看这篇【SpringBoot3教程导航帖】https://blog.csdn.net/weixin_43970743/article/details/151115907，你想学习的都被收集在内，快速投入学习！！两不误。
  
若还想学习更多，可直接前往《滚雪球学SpringBoot(全版本合集)》:https://blog.csdn.net/weixin_43970743/category_11599389.html，涵盖SpringBoot所有版本教学文章。

演示环境说明：

• 开发工具：IDEA 2021.3
• JDK版本： JDK 17（推荐使用 JDK 17 或更高版本，因为 Spring Boot 3.x 系列要求 Java 17，Spring Boot 3.5.4 基于 Spring Framework 6.x 和 Jakarta EE 9，它们都要求至少 JDK 17。）
• Spring Boot版本：3.5.4（于25年7月24日发布）
• Maven版本：3.8.2 （或更高）
• Gradle：（如果使用 Gradle 构建工具的话）：推荐使用 Gradle 7.5 或更高版本，确保与 JDK 17 兼容。
• 操作系统：Windows 11

1）集成 SpringDoc：为什么它能当 SpringFox 的“正统继任者”？

SpringDoc 的定位一句话就够：它在运行时扫描 Spring 应用（配置、注解、结构），自动推断并生成 OpenAPI 文档（JSON/YAML + UI）。
而且 SpringDoc 官方就写了“从 SpringFox 迁移”的页面：直接告诉你删掉 SpringFox + Swagger2 依赖，换成 springdoc starter，以及注解怎么一一替换。

1.1 依赖（Spring Boot 3 / WebMVC）

Maven：

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.8.15</version>
</dependency>

这个坐标和版本号在 SpringDoc 的迁移说明里就是明写的（官方示例）。

如果你是 WebFlux，对应 starter 是 springdoc-openapi-starter-webflux-ui（同一套思路，只是 starter 不同）。

1.2 跑起来后默认访问路径是啥？

你需要记住两个“默认入口”，以后和安全配置打交道全靠它：

• OpenAPI JSON：/v3/api-docs（可配置）
• Swagger UI：/swagger-ui.html（可配置；通常会引导到 UI 页面）

并且 SpringDoc 把这些都做成了标准配置项：

• springdoc.api-docs.path 默认 /v3/api-docs
• springdoc.swagger-ui.path 默认 /swagger-ui.html

2）@Tag、@Operation、@Schema：写对了，文档像产品；写错了，文档像事故现场 😵‍💫

先说个真实体验：

• “能生成文档”不难
• 难的是：文档能不能让别人第一次打开就愿意用
  所以注解不是“装饰品”，它是你 API 的门面。

2.1 @Tag：给接口分栏目，不然 Swagger UI 像杂物间

@Tag 可以加在 类 或 方法 上：类级别影响该 Controller 下所有接口，方法级别影响单个接口。

import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@Tag(name = "User", description = "用户相关接口")
@RestController
@RequestMapping("/api/users")
public class UserController {
  // ...
}

2.2 @Operation：每个接口“到底干嘛”，一句话说清楚

@Operation 是方法级注解，用于描述一个 OpenAPI Operation（summary/description 等）。

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

@Operation(
  summary = "根据ID查询用户",
  description = "用于管理后台详情页；如果用户不存在返回404"
)
@GetMapping("/{id}")
public UserDTO getUser(@PathVariable Long id) {
  // ...
}

小习惯：summary 写给“扫一眼的人”，description 写给“真要调用的人”。两者都写，文档气质立刻不一样。🙂

2.3 @Schema：模型字段解释清楚，前后端少吵 80%

@Schema 用来描述 OpenAPI 的 Schema：可以标在类、字段、参数、请求/响应内容等位置。

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

@Schema(name = "UserDTO", description = "用户信息返回模型")
public class UserDTO {

  @Schema(description = "用户ID", example = "10086")
  private Long id;

  @Schema(description = "昵称", example = "Loralie")
  private String nickname;

  @Schema(description = "手机号（脱敏）", example = "138****8888")
  private String mobile;

  // getters/setters
}

你会发现：当 example 足够真实、description 足够明确时，前端同学提问会明显变少——这不是玄学，是生产力。😄

2.4 从 SpringFox 注解迁移：官方给你对照表（省得你瞎猜）

SpringDoc 官方迁移页把常用注解替换写得很直白：

• @Api → @Tag
• @ApiModel / @ApiModelProperty → @Schema
• @ApiOperation → @Operation(summary/description)
  并且强调 swagger3 注解包就是 io.swagger.v3.oas.annotations。

3）配合 Spring Security：Swagger UI 放行，但别把生产环境“顺手开了后门”😬

启用 Spring Security 后，Swagger UI 访问经常直接 401/403——这很正常。你要做的是：在开发/测试环境放行文档端点，生产环境则更谨慎（比如仅内网、仅特定角色、或直接禁用）。

Baeldung（偏权威、工程化写法）给了 Boot 3 场景下“允许访问 Swagger UI”的典型配置思路：对 swagger-ui 和 api-docs 路径进行 permitAll，其余照常鉴权。

3.1 最常见的放行规则（Spring Security 6 / Boot 3）

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfig {

  @Bean
  SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    return http
      .authorizeHttpRequests(auth -> auth
        .requestMatchers(
          "/swagger-ui.html",
          "/swagger-ui/**",
          "/v3/api-docs/**"
        ).permitAll()
        .anyRequest().authenticated()
      )
      .httpBasic(Customizer.withDefaults())
      .build();
  }
}

这里放行的路径来源于 SpringDoc 的默认配置项：

• springdoc.swagger-ui.path 默认 /swagger-ui.html
• springdoc.api-docs.path 默认 /v3/api-docs

你如果改了 springdoc.api-docs.path，记得同步改 Security 放行路径，不然你会被自己“阴一把”。🙂

3.2 更稳一点的做法：用 Profile 控制（推荐）

开发环境：放行 + 允许 Try it out
生产环境：限制访问或直接禁用 swagger-ui

SpringDoc 提供开关：

• springdoc.swagger-ui.enabled 默认 true，可关闭
• springdoc.api-docs.enabled 默认 true，可关闭

示例（application-prod.yml）：

springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

我个人习惯是：生产环境默认关，需要时临时在内网开一会儿（或者通过网关白名单）。这事儿不“炫”，但真能救命。😅

4）多分组文档：Mobile API vs Web API（别把所有接口揉成一锅粥）

当你的项目出现 /api/mobile/**、/api/web/**、/api/admin/** 这种多端接口时，文档如果不分组——
打开 Swagger UI 的那一刻，体验基本等同于：在超市里找一根针。

SpringDoc 官方迁移页明确提到：如果你以前 SpringFox 有多个 Docket，在 SpringDoc 里对应换成多个 GroupedOpenApi。
并且给了 builder 示例：.group() + .pathsToMatch()。

4.1 用 GroupedOpenApi 分组（推荐，清晰可控）

import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiGroupConfig {

  @Bean
  public GroupedOpenApi mobileApi() {
    return GroupedOpenApi.builder()
      .group("Mobile API")
      .pathsToMatch("/api/mobile/**")
      .build();
  }

  @Bean
  public GroupedOpenApi webApi() {
    return GroupedOpenApi.builder()
      .group("Web API")
      .pathsToMatch("/api/web/**")
      .build();
  }
}

这套 builder 思路与迁移文档示例一致：group + pathsToMatch。
GroupedOpenApi 本身也是 SpringDoc 的核心类型之一（Javadoc 可查）。

4.2 用配置文件分组（适合“组很多”的情况）

SpringDoc 的 properties 页面里有 springdoc.group-configs[...] 这种配置入口（也就是“分组可以用配置驱动”）。
如果你组非常多，用配置比写一堆 Bean 更省心。

（示意）

springdoc:
  group-configs:
    - group: "Mobile API"
      paths-to-match: "/api/mobile/**"
    - group: "Web API"
      paths-to-match: "/api/web/**"

实战建议：组少（2~5 个）用 Bean；组多用配置文件，别让配置类变“豆腐渣工程”。😄

5）顺手把“文档门面”也做漂亮：全局 Info / 联系方式 / 版本

SpringDoc 迁移页也给了 OpenAPI Bean 示例：用 OpenAPI().info(new Info()...) 配标题、描述、版本等。

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

@Configuration
public class OpenApiMetaConfig {

  @Bean
  public OpenAPI appOpenAPI() {
    return new OpenAPI()
      .info(new Info()
        .title("My Service API")
        .description("内部服务接口文档（开发环境开放）")
        .version("v1.0.0"));
  }
}

说句很“人话”的：标题、描述、版本号这些玩意儿看似虚，但当你们团队开始多环境、多版本并行时，它真的能让人少骂两句。🙂

6）小结：这一套做完，你会得到什么？

• 依赖简单：加一个 starter 就能跑（官方迁移建议明确）
• 注解标准：@Tag / @Operation / @Schema 都是 swagger-annotations 的正统注解（Javadoc 清晰）
• 路径可控：/v3/api-docs、/swagger-ui.html 以及对应配置项在 SpringDoc 官方 properties 文档里写得明明白白
• 安全不裸奔：Spring Security 放行规则有成熟的 Boot 3 写法可参考
• 分组清爽：GroupedOpenApi 把 Mobile/Web 这种多端文档直接拆开，Swagger UI 终于“像个工具”而不是“像个迷宫”

🧧福利赠与你🧧

  无论你是计算机专业的学生，还是对编程有兴趣的小伙伴，都建议直接毫无顾忌的学习此专栏「滚雪球学SpringBoot」，bug菌郑重承诺，凡是学习此专栏的同学，均能获取到所需的知识和技能，全网最快速入门SpringBoot，就像滚雪球一样，越滚越大， 无边无际，指数级提升。

最后，如果这篇文章对你有所帮助，帮忙给作者来个一键三连，关注、点赞、收藏，您的支持就是我坚持写作最大的动力。

同时欢迎大家关注公众号:「猿圈奇妙屋」 ，以便学习更多同类型的技术文章，免费白嫖最新BAT互联网公司面试题、4000G PDF编程电子书、简历模板、技术文章Markdown文档等海量资料。

ps：本文涉及所有源代码，均已上传至Gitee：https://gitee.com/bugjun01/SpringBoot-demo 开源，供同学们一对一参考 Gitee传送门https://gitee.com/bugjun01/SpringBoot-demo，同时，原创开源不易，欢迎给个star🌟，想体验下被🌟的感jio，非常感谢❗

🫵 Who am I?

我是 bug菌：

• 热活跃于 CSDN:https://blog.csdn.net/weixin_43970743 | 掘金:https://juejin.cn/user/695333581765240 | InfoQ:https://www.infoq.cn/profile/4F581734D60B28/publish | 51CTO:https://blog.51cto.com/u_15700751 | 华为云:https://bbs.huaweicloud.com/community/usersnew/id_1582617489455371 | 阿里云:https://developer.aliyun.com/profile/uolxikq5k3gke | 腾讯云:https://cloud.tencent.com/developer/user/10216480/articles 等技术社区；
• CSDN 博客之星 Top30、华为云多年度十佳博主&卓越贡献奖、掘金多年度人气作者 Top40；
• 掘金、InfoQ、51CTO 等平台签约及优质作者；
• 全网粉丝累计 30w+。

更多高质量技术内容及成长资料，可查看这个合集入口 👉 点击查看:https://bbs.csdn.net/topics/612438251 👈️
硬核技术公众号 「猿圈奇妙屋」https://bbs.csdn.net/topics/612438251 期待你的加入，一起进阶、一起打怪升级。

- End -