之前在SpringBoot项目中一直使用的是SpringFox提供的Swagger库，上了下官网发现已经有接近两年没出新版本了！前几天升级了SpringBoot 2.6.x 版本，发现这个库的兼容性也越来越不好了，有的常用注解属性被废弃了居然都没提供替代！无意中发现了另一款Swagger库SpringDoc，试用了一下非常不错，推荐给大家！
SpringBoot实战电商项目mall（50k+star）地址：https://github.com/macrozheng/mall
SpringDoc简介SpringDoc是一款可以结合SpringBoot使用的API文档生成工具，基于OpenAPI 3，目前在Github上已有1.7K+Star，更新发版还是挺勤快的，是一款更好用的Swagger库！值得一提的是SpringDoc不仅支持Spring WebMvc项目，还可以支持Spring WebFlux项目，甚至Spring Rest和Spring Native项目，总之非常强大，下面是一张SpringDoc的架构图。
使用接下来我们介绍下SpringDoc的使用，使用的是之前集成SpringFox的mall-tiny-swagger项目，我将把它改造成使用SpringDoc。
集成首先我们得集成SpringDoc，在pom.xml中添加它的依赖即可，开箱即用，无需任何配置。
从SpringFox迁移 我们先来看下经常使用的Swagger注解，看看SpringFox的和SpringDoc的有啥区别，毕竟对比已学过的技术能该快掌握新技术； SpringFoxSpringDoc@Api@Tag@ApiIgnore@Parameter(hidden = true)or@Operation(hidden = true)or@Hidden@ApiImplicitParam@Parameter@ApiImplicitParams@Parameters@ApiModel@Schema@ApiModelProperty@Schema@ApiOperation(value = "foo", notes = "bar")@Operation(summary = "foo", description = "bar")@ApiParam@Parameter@ApiResponse(code = 404, message = "foo")ApiResponse(responseCode = "404", description = "foo")接下来我们对之前Controller中使用的注解进行改造，对照上表即可，之前在@Api注解中被废弃了好久又没有替代的description属性终于被支持了！
接下来进行SpringDoc的配置，使用OpenAPI来配置基础的文档信息，通过GroupedOpenApi配置分组的API文档，SpringDoc支持直接使用接口路径进行配置。
结合SpringSecurity使用由于我们的项目集成了SpringSecurity，需要通过JWT认证头进行访问，我们还需配置好SpringDoc的白名单路径，主要是Swagger的资源路径；
然后在OpenAPI对象中通过addSecurityItem方法和SecurityScheme对象，启用基于JWT的认证功能。
测试接下来启动项目就可以访问Swagger界面了，访问地址：http://localhost:8088/swagger-ui.html
我们先通过登录接口进行登录，可以发现这个版本的Swagger返回结果是支持高亮显示的，版本明显比SpringFox来的新；
然后通过认证按钮输入获取到的认证头信息，注意这里不用加bearer前缀；
之后我们就可以愉快地访问需要登录认证的接口了；
看一眼请求参数的文档说明，还是熟悉的Swagger样式！
常用配置SpringDoc还有一些常用的配置可以了解下，更多配置可以参考官方文档。
总结在SpringFox的Swagger库好久不出新版的情况下，迁移到SpringDoc确实是一个更好的选择。今天体验了一把SpringDoc，确实很好用，和之前熟悉的用法差不多，学习成本极低。而且SpringDoc能支持WebFlux之类的项目，功能也更加强大，使用SpringFox有点卡手的朋友可以迁移到它试试！
如果你想了解更多SpringBoot实战技巧的话，可以试试这个带全套教程的实战项目（50K+Star）：github.com/macrozheng/…
参考资料 项目地址：github.com/springdoc/s…官方文档：springdoc.org/项目源码地址 ：https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-springdoc
更多关于SpringBoot API文档工具SpringDoc的资料请关注七叶笔记其它相关文章！
