神器SpringDoc横空出世！最适合SpringBoot的

　　之前在SpringBoot项目中一直使用的是SpringFox提供的Swagger库，上了下官网发现已经有接近两年没出新版本了！前几天升级了SpringBoot2。6。x版本，发现这个库的兼容性也越来越不好了，有的常用注解属性被废弃了居然都没提供替代！无意中发现了另一款Swagger库SpringDoc，试用了一下非常不错，推荐给大家！SpringDoc简介
　　SpringDoc是一款可以结合SpringBoot使用的API文档生成工具，基于OpenAPI3，目前在Github上已有1。7KStar，更新发版还是挺勤快的，是一款更好用的Swagger库！值得一提的是SpringDoc不仅支持SpringWebMvc项目，还可以支持SpringWebFlux项目，甚至SpringRest和SpringNative项目，总之非常强大，下面是一张SpringDoc的架构图。
　　使用
　　接下来我们介绍下SpringDoc的使用，使用的是之前集成SpringFox的malltinyswagger项目，我将把它改造成使用SpringDoc。集成
　　首先我们得集成SpringDoc，在pom。xml中添加它的依赖即可，开箱即用，无需任何配置。！springdoc官方StarterdependencygroupIdorg。springdocgroupIdspringdocopenapiuiartifactIdversion1。6。6versiondependency从SpringFox迁移我们先来看下经常使用的Swagger注解，看看SpringFox的和SpringDoc的有啥区别，毕竟对比已学过的技术能该快掌握新技术；
　　接下来我们对之前Controller中使用的注解进行改造，对照上表即可，之前在Api注解中被废弃了好久又没有替代的description属性终于被支持了！品牌管理ControllerCreatedbymacroon2019419。Tag（namePmsBrandController，description商品品牌管理）ControllerRequestMapping（brand）publicclassPmsBrandController｛AutowiredprivatePmsBrandServicebrandService；privatestaticfinalLoggerLOGGERLoggerFactory。getLogger（PmsBrandController。class）；Operation（summary获取所有品牌列表，description需要登录后访问）RequestMapping（valuelistAll，methodRequestMethod。GET）ResponseBodypublicCommonResultListPmsBrandgetBrandList（）｛returnCommonResult。success（brandService。listAllBrand（））；｝Operation（summary添加品牌）RequestMapping（valuecreate，methodRequestMethod。POST）ResponseBodyPreAuthorize（hasRole（ADMIN））publicCommonResultcreateBrand（RequestBodyPmsBrandpmsBrand）｛CommonResultcommonResult；intcountbrandService。createBrand（pmsBrand）；if（count1）｛commonResultCommonResult。success（pmsBrand）；LOGGER。debug（createBrandsuccess：｛｝，pmsBrand）；｝else｛commonResultCommonResult。failed（操作失败）；LOGGER。debug（createBrandfailed：｛｝，pmsBrand）；｝returncommonResult；｝Operation（summary更新指定id品牌信息）RequestMapping（valueupdate｛id｝，methodRequestMethod。POST）ResponseBodyPreAuthorize（hasRole（ADMIN））publicCommonResultupdateBrand（PathVariable（id）Longid，RequestBodyPmsBrandpmsBrandDto，BindingResultresult）｛CommonResultcommonResult；intcountbrandService。updateBrand（id，pmsBrandDto）；if（count1）｛commonResultCommonResult。success（pmsBrandDto）；LOGGER。debug（updateBrandsuccess：｛｝，pmsBrandDto）；｝else｛commonResultCommonResult。failed（操作失败）；LOGGER。debug（updateBrandfailed：｛｝，pmsBrandDto）；｝returncommonResult；｝Operation（summary删除指定id的品牌）RequestMapping（valuedelete｛id｝，methodRequestMethod。GET）ResponseBodyPreAuthorize（hasRole（ADMIN））publicCommonResultdeleteBrand（PathVariable（id）Longid）｛intcountbrandService。deleteBrand（id）；if（count1）｛LOGGER。debug（deleteBrandsuccess：id｛｝，id）；returnCommonResult。success（null）；｝else｛LOGGER。debug（deleteBrandfailed：id｛｝，id）；returnCommonResult。failed（操作失败）；｝｝Operation（summary分页查询品牌列表）RequestMapping（valuelist，methodRequestMethod。GET）ResponseBodyPreAuthorize（hasRole（ADMIN））publicCommonResultCommonPagePmsBrandlistBrand（RequestParam（valuepageNum，defaultValue1）Parameter（description页码）IntegerpageNum，RequestParam（valuepageSize，defaultValue3）Parameter（description每页数量）IntegerpageSize）｛ListPmsBrandbrandListbrandService。listBrand（pageNum，pageSize）；returnCommonResult。success（CommonPage。restPage（brandList））；｝Operation（summary获取指定id的品牌详情）RequestMapping（value｛id｝，methodRequestMethod。GET）ResponseBodyPreAuthorize（hasRole（ADMIN））publicCommonResultPmsBrandbrand（PathVariable（id）Longid）｛returnCommonResult。success（brandService。getBrand（id））；｝｝接下来进行SpringDoc的配置，使用OpenAPI来配置基础的文档信息，通过GroupedOpenApi配置分组的API文档，SpringDoc支持直接使用接口路径进行配置。SpringDocAPI文档相关配置Createdbymacroon202234。ConfigurationpublicclassSpringDocConfig｛BeanpublicOpenAPImallTinyOpenAPI（）｛returnnewOpenAPI（）。info（newInfo（）。title（MallTinyAPI）。description（SpringDocAPI演示）。version（v1。0。0）。license（newLicense（）。name（Apache2。0）。url（https：github。commacrozhengmalllearning）））。externalDocs（newExternalDocumentation（）。description（SpringBoot实战电商项目mall（50KStar）全套文档）。url（http：www。macrozheng。com））；｝BeanpublicGroupedOpenApipublicApi（）｛returnGroupedOpenApi。builder（）。group（brand）。pathsToMatch（brand）。build（）；｝BeanpublicGroupedOpenApiadminApi（）｛returnGroupedOpenApi。builder（）。group（admin）。pathsToMatch（admin）。build（）；｝｝结合SpringSecurity使用由于我们的项目集成了SpringSecurity，需要通过JWT认证头进行访问，我们还需配置好SpringDoc的白名单路径，主要是Swagger的资源路径；SpringSecurity的配置Createdbymacroon2018426。ConfigurationEnableWebSecurityEnableGlobalMethodSecurity（prePostEnabledtrue）publicclassSecurityConfigextendsWebSecurityConfigurerAdapter｛Overrideprotectedvoidconfigure（HttpSecurityhttpSecurity）throwsException｛httpSecurity。csrf（）由于使用的是JWT，我们这里不需要csrf。disable（）。sessionManagement（）基于token，所以不需要session。sessionCreationPolicy（SessionCreationPolicy。STATELESS）。and（）。authorizeRequests（）。antMatchers（HttpMethod。GET，Swagger的资源路径需要允许访问，swaggerui。html，swaggerui，。html，favicon。ico，。html，。css，。js，swaggerresources，v3apidocs）。permitAll（）。antMatchers（adminlogin）对登录注册要允许匿名访问。permitAll（）。antMatchers（HttpMethod。OPTIONS）跨域请求会先进行一次options请求。permitAll（）。anyRequest（）除上面外的所有请求全部需要鉴权认证。authenticated（）；｝｝然后在OpenAPI对象中通过addSecurityItem方法和SecurityScheme对象，启用基于JWT的认证功能。SpringDocAPI文档相关配置Createdbymacroon202234。ConfigurationpublicclassSpringDocConfig｛privatestaticfinalStringSECURITYSCHEMENAMEBearerAuth；BeanpublicOpenAPImallTinyOpenAPI（）｛returnnewOpenAPI（）。info（newInfo（）。title（MallTinyAPI）。description（SpringDocAPI演示）。version（v1。0。0）。license（newLicense（）。name（Apache2。0）。url（https：github。commacrozhengmalllearning）））。externalDocs（newExternalDocumentation（）。description（SpringBoot实战电商项目mall（50KStar）全套文档）。url（http：www。macrozheng。com））。addSecurityItem（newSecurityRequirement（）。addList（SECURITYSCHEMENAME））。components（newComponents（）。addSecuritySchemes（SECURITYSCHEMENAME，newSecurityScheme（）。name（SECURITYSCHEMENAME）。type（SecurityScheme。Type。HTTP）。scheme（bearer）。bearerFormat（JWT）））；｝｝测试接下来启动项目就可以访问Swagger界面了，访问地址：http：localhost：8088swaggerui。html
　　我们先通过登录接口进行登录，可以发现这个版本的Swagger返回结果是支持高亮显示的，版本明显比SpringFox来的新；
　　然后通过认证按钮输入获取到的认证头信息，注意这里不用加bearer前缀；
　　之后我们就可以愉快地访问需要登录认证的接口了；
　　看一眼请求参数的文档说明，还是熟悉的Swagger样式！
　　常用配置
　　SpringDoc还有一些常用的配置可以了解下，更多配置可以参考官方文档。springdoc：swaggerui：修改SwaggerUI路径path：swaggerui。html开启SwaggerUI界面enabled：trueapidocs：修改apidocs路径path：v3apidocs开启apidocsenabled：true配置需要生成接口文档的扫描包packagestoscan：com。macro。mall。tiny。controller配置需要生成接口文档的接口路径pathstomatch：brand，admin总结
　　在SpringFox的Swagger库好久不出新版的情况下，迁移到SpringDoc确实是一个更好的选择。今天体验了一把SpringDoc，确实很好用，和之前熟悉的用法差不多，学习成本极低。而且SpringDoc能支持WebFlux之类的项目，功能也更加强大，使用SpringFox有点卡手的朋友可以迁移到它试试！参考资料项目地址：https：github。comspringdocspringdocopenapi官方文档：https：springdoc。org项目源码地址
　　https：github。commacrozhengmalllearningtreemastermalltinyspringdoc
　　来源：https：mp。weixin。qq。comsscityFhZp9BOJorZSdCG0w