当前位置：首页 > news >正文

SpringBoot 接口文档自动生成：SpringDoc + OpenAPI 3.0

news 2026/5/26 20:35:40

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

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

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

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

支持 OpenAPI 3.0 规范
（最新行业标准）
兼容 SpringBoot 2.6x / 2.7x / 3.x
（Swagger不兼容高版本Boot）
无侵入、零配置
，不污染业务代码
性能更好、体积更小
支持 SpringBoot 官方推荐
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，所有接口自动携带。