devbox
Gausst松鼠会
这个屌丝很懒，什么也没留下！
关注作者
热门标签
热门文章
当前位置:   article > 正文

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

作者：Gausst松鼠会 | 2024-05-16 18:46:26

赞

踩

springboot3 springdoc

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

  1. <!--springdoc 官方Starter-->
  2. <dependency>
  3.     <groupId>org.springdoc</groupId>
  4.     <artifactId>springdoc-openapi-ui</artifactId>
  5.     <version>1.6.6</version>
  6. </dependency>

从SpringFox迁移

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

  • 接下来我们对之前Controller中使用的注解进行改造，对照上表即可，之前在@Api注解中被废弃了好久又没有替代的description属性终于被支持了！
  1. /**
  2.  * 品牌管理Controller
  3.  * Created by macro on 2019/4/19.
  4.  */
  5. @Tag(name = "PmsBrandController", description = "商品品牌管理")
  6. @Controller
  7. @RequestMapping("/brand")
  8. public class PmsBrandController {
  9.     @Autowired
  10.     private PmsBrandService brandService;
  11.  
  12.     private static final Logger LOGGER = LoggerFactory.getLogger(PmsBrandController.class);
  13.  
  14.     @Operation(summary = "获取所有品牌列表",description = "需要登录后访问")
  15.     @RequestMapping(value = "listAll", method = RequestMethod.GET)
  16.     @ResponseBody
  17.     public CommonResult<List<PmsBrand>> getBrandList() {
  18.         return CommonResult.success(brandService.listAllBrand());
  19.     }
  20.  
  21.     @Operation(summary = "添加品牌")
  22.     @RequestMapping(value = "/create", method = RequestMethod.POST)
  23.     @ResponseBody
  24.     @PreAuthorize("hasRole('ADMIN')")
  25.     public CommonResult createBrand(@RequestBody PmsBrand pmsBrand) {
  26.         CommonResult commonResult;
  27.         int count = brandService.createBrand(pmsBrand);
  28.         if (count == 1) {
  29.             commonResult = CommonResult.success(pmsBrand);
  30.             LOGGER.debug("createBrand success:{}", pmsBrand);
  31.         } else {
  32.             commonResult = CommonResult.failed("操作失败");
  33.             LOGGER.debug("createBrand failed:{}", pmsBrand);
  34.         }
  35.         return commonResult;
  36.     }
  37.  
  38.     @Operation(summary = "更新指定id品牌信息")
  39.     @RequestMapping(value = "/update/{id}", method = RequestMethod.POST)
  40.     @ResponseBody
  41.     @PreAuthorize("hasRole('ADMIN')")
  42.     public CommonResult updateBrand(@PathVariable("id") Long id, @RequestBody PmsBrand pmsBrandDto, BindingResult result) {
  43.         CommonResult commonResult;
  44.         int count = brandService.updateBrand(id, pmsBrandDto);
  45.         if (count == 1) {
  46.             commonResult = CommonResult.success(pmsBrandDto);
  47.             LOGGER.debug("updateBrand success:{}", pmsBrandDto);
  48.         } else {
  49.             commonResult = CommonResult.failed("操作失败");
  50.             LOGGER.debug("updateBrand failed:{}", pmsBrandDto);
  51.         }
  52.         return commonResult;
  53.     }
  54.  
  55.     @Operation(summary = "删除指定id的品牌")
  56.     @RequestMapping(value = "/delete/{id}", method = RequestMethod.GET)
  57.     @ResponseBody
  58.     @PreAuthorize("hasRole('ADMIN')")
  59.     public CommonResult deleteBrand(@PathVariable("id") Long id) {
  60.         int count = brandService.deleteBrand(id);
  61.         if (count == 1) {
  62.             LOGGER.debug("deleteBrand success :id={}", id);
  63.             return CommonResult.success(null);
  64.         } else {
  65.             LOGGER.debug("deleteBrand failed :id={}", id);
  66.             return CommonResult.failed("操作失败");
  67.         }
  68.     }
  69.  
  70.     @Operation(summary = "分页查询品牌列表")
  71.     @RequestMapping(value = "/list", method = RequestMethod.GET)
  72.     @ResponseBody
  73.     @PreAuthorize("hasRole('ADMIN')")
  74.     public CommonResult<CommonPage<PmsBrand>> listBrand(@RequestParam(value = "pageNum", defaultValue = "1")
  75.                                                         @Parameter(description = "页码") Integer pageNum,
  76.                                                         @RequestParam(value = "pageSize", defaultValue = "3")
  77.                                                         @Parameter(description = "每页数量") Integer pageSize) {
  78.         List<PmsBrand> brandList = brandService.listBrand(pageNum, pageSize);
  79.         return CommonResult.success(CommonPage.restPage(brandList));
  80.     }
  81.  
  82.     @Operation(summary = "获取指定id的品牌详情")
  83.     @RequestMapping(value = "/{id}", method = RequestMethod.GET)
  84.     @ResponseBody
  85.     @PreAuthorize("hasRole('ADMIN')")
  86.     public CommonResult<PmsBrand> brand(@PathVariable("id") Long id) {
  87.         return CommonResult.success(brandService.getBrand(id));
  88.     }
  89. }
  • 接下来进行SpringDoc的配置，使用OpenAPI来配置基础的文档信息，通过GroupedOpenApi配置分组的API文档，SpringDoc支持直接使用接口路径进行配置。
  1. /**
  2.  * SpringDoc API文档相关配置
  3.  * Created by macro on 2022/3/4.
  4.  */
  5. @Configuration
  6. public class SpringDocConfig {
  7.     @Bean
  8.     public OpenAPI mallTinyOpenAPI() {
  9.         return new OpenAPI()
  10.                 .info(new Info().title("Mall-Tiny API")
  11.                         .description("SpringDoc API 演示")
  12.                         .version("v1.0.0")
  13.                         .license(new License().name("Apache 2.0").url("https://github.com/macrozheng/mall-learning")))
  14.                 .externalDocs(new ExternalDocumentation()
  15.                         .description("SpringBoot实战电商项目mall（50K+Star）全套文档")
  16.                         .url("http://www.macrozheng.com"));
  17.     }
  18.  
  19.     @Bean
  20.     public GroupedOpenApi publicApi() {
  21.         return GroupedOpenApi.builder()
  22.                 .group("brand")
  23.                 .pathsToMatch("/brand/**")
  24.                 .build();
  25.     }
  26.  
  27.     @Bean
  28.     public GroupedOpenApi adminApi() {
  29.         return GroupedOpenApi.builder()
  30.                 .group("admin")
  31.                 .pathsToMatch("/admin/**")
  32.                 .build();
  33.     }
  34. }

结合SpringSecurity使用

  • 由于我们的项目集成了SpringSecurity，需要通过JWT认证头进行访问，我们还需配置好SpringDoc的白名单路径，主要是Swagger的资源路径；
  1. /**
  2.  * SpringSecurity的配置
  3.  * Created by macro on 2018/4/26.
  4.  */
  5. @Configuration
  6. @EnableWebSecurity
  7. @EnableGlobalMethodSecurity(prePostEnabled = true)
  8. public class SecurityConfig extends WebSecurityConfigurerAdapter {                                              
  9.  
  10.     @Override
  11.     protected void configure(HttpSecurity httpSecurity) throws Exception {
  12.         httpSecurity.csrf()// 由于使用的是JWT，我们这里不需要csrf
  13.                 .disable()
  14.                 .sessionManagement()// 基于token，所以不需要session
  15.                 .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
  16.                 .and()
  17.                 .authorizeRequests()
  18.                 .antMatchers(HttpMethod.GET, // Swagger的资源路径需要允许访问
  19.                         "/",   
  20.                         "/swagger-ui.html",
  21.                         "/swagger-ui/",
  22.                         "/*.html",
  23.                         "/favicon.ico",
  24.                         "/**/*.html",
  25.                         "/**/*.css",
  26.                         "/**/*.js",
  27.                         "/swagger-resources/**",
  28.                         "/v3/api-docs/**"
  29.                 )
  30.                 .permitAll()
  31.                 .antMatchers("/admin/login")// 对登录注册要允许匿名访问
  32.                 .permitAll()
  33.                 .antMatchers(HttpMethod.OPTIONS)//跨域请求会先进行一次options请求
  34.                 .permitAll()
  35.                 .anyRequest()// 除上面外的所有请求全部需要鉴权认证
  36.                 .authenticated();
  37.         
  38.     }
  39.  
  40. }
  • 然后在OpenAPI对象中通过addSecurityItem方法和SecurityScheme对象，启用基于JWT的认证功能。
  1. /**
  2.  * SpringDoc API文档相关配置
  3.  * Created by macro on 2022/3/4.
  4.  */
  5. @Configuration
  6. public class SpringDocConfig {
  7.     private static final String SECURITY_SCHEME_NAME = "BearerAuth";
  8.     @Bean
  9.     public OpenAPI mallTinyOpenAPI() {
  10.         return new OpenAPI()
  11.                 .info(new Info().title("Mall-Tiny API")
  12.                         .description("SpringDoc API 演示")
  13.                         .version("v1.0.0")
  14.                         .license(new License().name("Apache 2.0").url("https://github.com/macrozheng/mall-learning")))
  15.                 .externalDocs(new ExternalDocumentation()
  16.                         .description("SpringBoot实战电商项目mall（50K+Star）全套文档")
  17.                         .url("http://www.macrozheng.com"))
  18.                 .addSecurityItem(new SecurityRequirement().addList(SECURITY_SCHEME_NAME))
  19.                 .components(new Components()
  20.                                 .addSecuritySchemes(SECURITY_SCHEME_NAME,
  21.                                         new SecurityScheme()
  22.                                                 .name(SECURITY_SCHEME_NAME)
  23.                                                 .type(SecurityScheme.Type.HTTP)
  24.                                                 .scheme("bearer")
  25.                                                 .bearerFormat("JWT")));
  26.     }
  27. }

测试

  • 接下来启动项目就可以访问Swagger界面了，访问地址：http://localhost:8088/swagger-ui.html

  • 我们先通过登录接口进行登录，可以发现这个版本的Swagger返回结果是支持高亮显示的，版本明显比SpringFox来的新；

  • 然后通过认证按钮输入获取到的认证头信息，注意这里不用加bearer前缀；

  • 之后我们就可以愉快地访问需要登录认证的接口了；

  • 看一眼请求参数的文档说明，还是熟悉的Swagger样式！

常用配置

SpringDoc还有一些常用的配置可以了解下，更多配置可以参考官方文档。

  1. springdoc:
  2.   swagger-ui:
  3.     # 修改Swagger UI路径
  4.     path: /swagger-ui.html
  5.     # 开启Swagger UI界面
  6.     enabled: true
  7.   api-docs:
  8.     # 修改api-docs路径
  9.     path: /v3/api-docs
  10.     # 开启api-docs
  11.     enabled: true
  12.   # 配置需要生成接口文档的扫描包
  13.   packages-to-scan: com.macro.mall.tiny.controller
  14.   # 配置需要生成接口文档的接口路径
  15.   paths-to-match: /brand/**,/admin/**

总结

在SpringFox的Swagger库好久不出新版的情况下，迁移到SpringDoc确实是一个更好的选择。今天体验了一把SpringDoc，确实很好用，和之前熟悉的用法差不多，学习成本极低。而且SpringDoc能支持WebFlux之类的项目，功能也更加强大，使用SpringFox有点卡手的朋友可以迁移到它试试！

参考资料

  • 项目地址：https://github.com/springdoc/springdoc-openapi
  • 官方文档：https://springdoc.org/

项目源码地址

https://github.com/macrozheng/mall-learning/tree/master/mall-tiny-springdoc

来源：
https://mp.weixin.qq.com/s/scityFhZp9BOJorZSdCG0w

声明：本文内容由网友自发贡献，不代表【wpsshop博客】立场，版权归原作者所有，本站不承担相应法律责任。如您发现有侵权的内容，请联系我们。转载请注明出处：https://www.wpsshop.cn/w/Gausst松鼠会/article/detail/580053
推荐阅读
相关标签

Copyright © 2003-2013 www.wpsshop.cn 版权所有，并保留所有权利。

  

闽ICP备14008679号