在前后端分离项目中，接口文档是刚需。
传统手写文档效率低、更新不及时、容易和代码不一致，沟通成本极高。

SpringBoot 官方早已放弃旧版 SpringFox（Swagger2），转而推荐更轻量、更强大的 SpringDoc + OpenAPI 3.0。

今天我们来实现接口文档自动生成、在线调试、权限配置、分组管理、生产环境关闭。

---

一、为什么选 SpringDoc，而不是 Swagger2？

1. 支持 OpenAPI 3.0 规范

   （最新行业标准）

2. 兼容 SpringBoot 2.6x / 2.7x / 3.x

   （Swagger不兼容高版本Boot）

3. 无侵入、零配置

   ，不污染业务代码

4. 性能更好、体积更小
5. 支持 SpringBoot 官方推荐
6. UI 更美观、调试更方便

---

二、核心依赖

直接在 pom.xml 添加，无需其他依赖：

1
2<dependency>
3<groupId>org.springdocgroupId>
4<artifactId>springdoc-openapi-uiartifactId>
5<version>1.7.0version>
6dependency>

SpringBoot 3.x 用这个：

1<dependency>
2<groupId>org.springdocgroupId>
3<artifactId>springdoc-openapi-starter-webmvc-uiartifactId>
4<version>2.2.0version>
5dependency>

---

三、启动

引入依赖后，什么都不用配！

直接启动项目，访问地址：

http://localhost:8080/swagger-ui.html

就能看到全自动生成的接口文档，支持：

• 自动扫描所有 Controller

• 自动解析参数、返回值

• 在线发送请求调试

• 自动展示实体类字段

---

四、相关配置

创建配置类 SpringDocConfig.java，定义文档标题、描述、版本、作者：

1importio.swagger.v3.oas.models.OpenAPI;
2importio.swagger.v3.oas.models.info.Contact;
3importio.swagger.v3.oas.models.info.Info;
4importorg.springframework.context.annotation.Bean;
5importorg.springframework.context.annotation.Configuration;
6
7@Configuration
8publicclassSpringDocConfig{
9
10@Bean
11publicOpenAPIspringShopOpenAPI(){
12returnnewOpenAPI()
13.info(newInfo()
14.title("SpringBoot 实战项目 API 文档")
15.description("接口文档自动生成 | 在线调试")
16.version("v1.0.0")
17.contact(newContact()
18.name("后端开发")
19.email("developer@demo.com")
20)
21);
22}
23}

---

五、常用注解

SpringDoc 使用 OpenAPI 3 注解，比 Swagger 更简洁。

1. 控制层注解

1importio.swagger.v3.oas.annotations.Operation;
2importio.swagger.v3.oas.annotations.tags.Tag;
3
4@RestController
5@RequestMapping("/user")
6@Tag(name ="用户管理模块", description ="用户增删改查接口")
7publicclassUserController{
8
9@Operation(summary ="根据ID查询用户", description ="传入用户ID，返回用户详情")
10@GetMapping("/{id}")
11publicResult<User>getUserById(@PathVariableInteger id){
12returnResult.success();
13}
14}

2. 实体/参数注解

1importio.swagger.v3.oas.annotations.media.Schema;
2
3@Data
4@Schema(description ="用户信息实体")
5publicclassUser{
6
7@Schema(description ="用户ID", example ="1001")
8privateInteger id;
9
10@Schema(description ="用户名", example ="zhangsan")
11privateString username;
12}

3. 隐藏接口

1@Operation(hidden =true)
2@GetMapping("/test")
3publicStringtest(){
4return"test";
5}

---

六、application.yml 增强配置

1springdoc:
2  api-docs:
3enabled:true# 是否开启接口文档（生产设为false）
4path: /v3/api-docs  # 文档JSON地址
5  swagger-ui:
6enabled:true# 是否开启UI页面
7path: /swagger-ui.html  # 访问路径
8tags-sorter: alpha  # 按字母排序
9operations-sorter: alpha  # 接口排序
10packages-to-scan: com.demo.controller  # 只扫描Controller包

✅ 生产环境务必关闭文档：

springdoc.api-docs.enabled=false
springdoc.swagger-ui.enabled=false

---

七、带 Token 权限的接口调试

如果项目有登录认证（Token/JWT），配置文档自动带请求头：

1@Bean
2publicOpenAPIopenAPI(){
3returnnewOpenAPI()
4.info(newInfo()
5.title("API文档")
6.version("v1.0")
7)
8// 添加全局Token请求头
9.components(newComponents()
10.addSecuritySchemes("token",
11newSecurityScheme()
12.type(SecurityScheme.Type.APIKEY)
13.in(SecurityScheme.In.HEADER)
14.name("token")
15)
16);
17}

页面上直接输入 Token，所有接口自动携带。

---

八、接口文档效果

访问：http://localhost:8080/swagger-ui.html

你会看到：

• 模块分组清晰

• 接口说明完整

• 参数自动解析

• 支持在线调试

• 返回结构自动展示（Result）

---

学会 SpringDoc，你再也不用手写接口文档，前后端对接效率直接翻倍！

---