最适合 SpringBoot 的API文档工具来了

之前在SpringBoot项目中一直使用的是SpringFox提供的Swagger库，上了下官网发现已经有接近两年没出新版本了！前几天升级了SpringBoot 2.6.x 版本，发现这个库的兼容性也越来越不好了，有的常用注解属性被废弃了居然都没提供替代！无意中发现了另一款Swagger库SpringDoc，试用了一下非常不错，推荐给大家！

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中添加它的依赖即可，开箱即用，无需任何配置。

<!--springdoc 官方Starter--> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.6.6</version> </dependency>

从SpringFox迁移

• 我们先来看下经常使用的Swagger注解，看看SpringFox的和SpringDoc的有啥区别，毕竟对比已学过的技术能该快掌握新技术；

• 接下来我们对之前Controller中使用的注解进行改造，对照上表即可，之前在@Api注解中被废弃了好久又没有替代的description属性终于被支持了！

/** * 品牌管理Controller * Created by macro on 2019/4/19. */ @Tag(name = "PmsBrandController", description = "商品品牌管理") @Controller @RequestMapping("/brand") public class PmsBrandController { @Autowired private PmsBrandService brandService; private static final Logger LOGGER = LoggerFactory.getLogger(PmsBrandController.class); @Operation(su