我要评论在前后端分离项目中，接口文档是刚需。
传统手写文档效率低、更新不及时、容易和代码不一致，沟通成本极高。
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接口文档自动生成的资料请关注代码网其它相关文章！
发表评论