首页 > 软件编程 > java > SpringBoot接口文档自动生成

SpringBoot使用SpringDoc+OpenAPI3.0实现接口文档自动生成

2026-03-31 09:32:16 作者：希望永不加班

本文介绍了在前后端分离项目中使用SpringDoc实现接口文档自动生成的方法,包括核心依赖、启动配置、常用注解、生产环境配置、带Token权限接口调试等内容,提高了接口文档的生成效率和维护性,需要的朋友可以参考下

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

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 添加，无需其他依赖：

<dependency>
<groupId>org.springdocgroupId>
<artifactId>springdoc-openapi-uiartifactId>
<version>1.7.0version>
<dependency>

SpringBoot 3.x 用这个：

<dependency>
<groupId>org.springdocgroupId>
<artifactId>springdoc-openapi-starter-webmvc-uiartifactId>
<version>2.2.0version>
<dependency>

三、启动

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

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

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

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

自动扫描所有 Controller
自动解析参数、返回值
在线发送请求调试
自动展示实体类字段

四、相关配置

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

importio.swagger.v3.oas.models.OpenAPI;
importio.swagger.v3.oas.models.info.Contact;
importio.swagger.v3.oas.models.info.Info;
importorg.springframework.context.annotation.Bean;
importorg.springframework.context.annotation.Configuration;
@Configuration
publicclassSpringDocConfig{
@Bean
publicOpenAPIspringShopOpenAPI(){
returnnewOpenAPI()
info(newInfo()
title("SpringBoot 实战项目 API 文档")
description("接口文档自动生成 | 在线调试")
version("v1.0.0")
name("后端开发")
email("developer@demo.com")
)
);
}
}

五、常用注解

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

1. 控制层注解

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

2. 实体/参数注解

importio.swagger.v3.oas.annotations.media.Schema;
@Data
@Schema(description ="用户信息实体")
publicclassUser{
@Schema(description ="用户ID", example ="1001")
privateInteger id;
@Schema(description ="用户名", example ="zhangsan")
privateString username;
}

3. 隐藏接口

@Operation(hidden =true)
@GetMapping("/test")
publicStringtest(){
return"test";
}

六、application.yml 增强配置

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

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

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

七、带 Token 权限的接口调试

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

@Bean
publicOpenAPIopenAPI(){
returnnewOpenAPI()
.info(newInfo()
title("API文档")
version("v1.0")
)
// 添加全局Token请求头
components(newComponents()
addSecuritySchemes("token",
newSecurityScheme()
type(SecurityScheme.Type.APIKEY)
in(SecurityScheme.In.HEADER)
name("token")
)
);
}

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

八、接口文档效果

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

你会看到：

模块分组清晰
接口说明完整
参数自动解析
支持在线调试
返回结构自动展示（Result）

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

以上就是SpringBoot使用SpringDoc+OpenAPI3.0实现接口文档自动生成的详细内容，更多关于SpringBoot接口文档自动生成的资料请关注脚本之家其它相关文章！