神器 SpringDoc 横空出世！最适合 SpringBoot 的API文档工具来了

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

SpringDoc简介

SpringDoc是一款可以结合SpringBoot使用的API文档生成工具，基于OpenAPI 3，目前在Github上已有17K+Star，更新发版还是挺勤快的，是一款更好用的Swagger库！值得一提的是SpringDoc不仅支持Spring WebMvc项目，还可以支持Spring WebFlux项目，甚至Spring Rest和Spring Native项目，总之非常强大，下面是一张SpringDoc的架构图。

使用

接下来我们介绍下SpringDoc的使用，使用的是之前集成SpringFox的mall-tiny-swagger项目，我将把它改造成使用SpringDoc。

集成

首先我们得集成SpringDoc，在pomxml中添加它的依赖即可，开箱即用，无需任何配置。

<!--springdoc 官方Starter-->orgspringdocspringdoc-openapi-ui166

从SpringFox迁移

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

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

/

品牌管理Controller

Created by macro on 2019/4/19

/@Tag(name ="PmsBrandController", description ="商品品牌管理")@Controller@RequestMapping("/brand")publicclassPmsBrandController{@AutowiredprivatePmsBrandService brandService;privatestaticfinalLogger LOGGER = LoggerFactorygetLogger(PmsBrandControllerclass);@Operation(summary ="获取所有品牌列表",description ="需要登录后访问")@RequestMapping(value ="listAll", method = RequestMethodGET)@ResponseBodypublicCommonResult> getBrandList() {returnCommonResultsuccess(brandServicelistAllBrand());    }@Operation(summary ="添加品牌")@RequestMapping(value ="/create", method = RequestMethodPOST)@ResponseBody@PreAuthorize("hasRole('ADMIN')")publicCommonResult createBrand(@RequestBodyPmsBrand pmsBrand) {        CommonResult commonResult;        int count = brandServicecreateBrand(pmsBrand);if(count ==1) {            commonResult = CommonResultsuccess(pmsBrand);            LOGGERdebug("createBrand success:{}", pmsBrand);        }else{            commonResult = CommonResultfailed(" *** 作失败");            LOGGERdebug("createBrand failed:{}", pmsBrand);        }returncommonResult;    }@Operation(summary ="更新指定id品牌信息")@RequestMapping(value ="/update/{id}", method = RequestMethodPOST)@ResponseBody@PreAuthorize("hasRole('ADMIN')")publicCommonResult updateBrand(@PathVariable("id")Longid,@RequestBodyPmsBrand pmsBrandDto, BindingResult result) {        CommonResult commonResult;        int count = brandServiceupdateBrand(id, pmsBrandDto);if(count ==1) {            commonResult = CommonResultsuccess(pmsBrandDto);            LOGGERdebug("updateBrand success:{}", pmsBrandDto);        }else{            commonResult = CommonResultfailed(" *** 作失败");            LOGGERdebug("updateBrand failed:{}", pmsBrandDto);        }returncommonResult;    }@Operation(summary ="删除指定id的品牌")@RequestMapping(value ="/delete/{id}", method = RequestMethodGET)@ResponseBody@PreAuthorize("hasRole('ADMIN')")publicCommonResult deleteBrand(@PathVariable("id")Longid) {        int count = brandServicedeleteBrand(id);if(count ==1) {            LOGGERdebug("deleteBrand success :id={}", id);returnCommonResultsuccess(null);        }else{            LOGGERdebug("deleteBrand failed :id={}", id);returnCommonResultfailed(" *** 作失败");        }    }@Operation(summary ="分页查询品牌列表")@RequestMapping(value ="/list", method = RequestMethodGET)@ResponseBody@PreAuthorize("hasRole('ADMIN')")publicCommonResult> listBrand(@RequestParam(value ="pageNum", defaultValue ="1")@Parameter(description ="页码")Integer pageNum,@RequestParam(value ="pageSize", defaultValue ="3")@Parameter(description ="每页数量")Integer pageSize) {        List brandList = brandServicelistBrand(pageNum, pageSize);returnCommonResultsuccess(CommonPagerestPage(brandList));    }@Operation(summary ="获取指定id的品牌详情")@RequestMapping(value ="/{id}", method = RequestMethodGET)@ResponseBody@PreAuthorize("hasRole('ADMIN')")publicCommonResult brand(@PathVariable("id")Longid) {returnCommonResultsuccess(brandServicegetBrand(id));    }}

接下来进行SpringDoc的配置，使用OpenAPI来配置基础的文档信息，通过GroupedOpenApi配置分组的API文档，SpringDoc支持直接使用接口路径进行配置。

/

SpringDoc API文档相关配置

Created by macro on 2022/3/4

/@ConfigurationpublicclassSpringDocConfig{@BeanpublicOpenAPImallTinyOpenAPI(){returnnewOpenAPI()                info(newInfo()title("Mall-Tiny API")                        description("SpringDoc API 演示")                        version("v100")                        license(newLicense()name("Apache 20")url(">

经过上面配置后,页面请求的每个静态文件必须包含/res/，这样静态文件才能映射到static-locations路径,没有配置就使用默认的。规范所有静态资源统一前缀，在使用shiro等拦截工具时，可以匹配/res/ 不进行权限检查。

资源缓存一般用于缓存应用静态资源和webjars下面的资源，默认情况下，springboot会配置/webjars/对应classpath:/META-INF/resources/webjars/的资源映射并进行缓存配置，static-path-pattern也会对应static-locations进行缓存配置。

第一种将资源文件放在源码里面：

那么配置文件信息如下：

<!-- 读取国际化资源文件 == 资源文件在包里面，路径写全包名-->

<bean id="messageSource"

class="orgspringframeworkcontextsupportResourceBundleMessageSource">

<property name="basenames">

<list>

<value>cn/ddx/i18n/messages</value>

</list>

</property>

</bean>

第二种配置文件在WEB-INF下面自己创建的目录下面：

那么配置文件信息如下：

<!-- 读取国际化资源文件 == 资源文件在WEB-INF下面 ，可以配置多个 -->

<bean id="messageSource"

class="orgspringframeworkcontextsupportReloadableResourceBundleMessageSource">

<property name="basenames">

<list>

<value>/WEB-INF/lang/messages</value>

</list>

</property>

</bean>

需要注意的是两者配置的class不同

配置文件路径中的“messages”为资源文件名称中_en_USproperties的前面部分，可以自定义。

在applicationyml或者properties文件中添加：

infoaddress=USA

infocompany=Spring

infodegree=high

激活 @ConfigurationProperties

我们可以通过下面几种方式将其添加到应用上下文中

首先，我们可以通过添加 @Component 注解让 Component Scan 扫描到

资源目录下建立config/db-configproperties:

dbusername=root

dbpassword=123456

@Autowired

private Environment env;

// 获取参数

String getProperty(String key);

@conditionalonproperty(name = "XXX",havingValue = "true")

参考文献

在软件中查看。将classpath：/static2/目录下的资源路径作为静态资源目录，实现虚拟目录的效果，即可查看配置的虚拟目录。虚拟服务器可拥有一个宿主目录和任意数量的其它发布目录，其它发布目录称为虚拟目录。

以上就是关于神器 SpringDoc 横空出世！最适合 SpringBoot 的API文档工具来了全部的内容，包括:神器 SpringDoc 横空出世！最适合 SpringBoot 的API文档工具来了、Springboot项目和dist文件启动之后为什么访问数据的路劲重复了、SpringBoot下静态资源处理等相关内容解答，如果想了解更多相关内容，可以关注我们，你们的支持是我们更新的动力！