首页 > 编程语言 >Java21 + SpringBoot3整合springdoc-openapi,自动生成在线接口文档,支持SpringSecurity和JWT认证方式

Java21 + SpringBoot3整合springdoc-openapi,自动生成在线接口文档,支持SpringSecurity和JWT认证方式

时间:2024-01-31 10:49:04浏览次数:30  
标签:Java21 swagger SpringSecurity API ui springdoc 文档 Swagger

目录

前言

近日心血来潮想做一个开源项目,目标是做一款可以适配多端、功能完备的模板工程,包含后台管理系统和前台系统,开发者基于此项目进行裁剪和扩展来完成自己的功能开发。

本项目为前后端分离开发,后端基于Java21SpringBoot3开发,后端使用Spring SecurityJWTSpring Data JPA等技术栈,前端提供了vueangularreactuniapp微信小程序等多种脚手架工程。

本文主要介绍在SpringBoot3项目中如何整合springdoc-openapi实现自动生成在线接口文档,JDK版本是Java21

项目地址:https://gitee.com/breezefaith/fast-alden

相关技术简介

OpenAPI

OpenAPI 规范(OAS),是定义一个标准的、与具体编程语言无关的RESTful API的规范。OpenAPI 规范使得人类和计算机都能在“不接触任何程序源代码和文档、不监控网络通信”的情况下理解一个服务的作用。如果您在定义您的 API 时做的很好,那么使用 API 的人就能非常轻松地理解您提供的 API 并与之交互了。

如果您遵循 OpenAPI 规范来定义您的 API,那么您就可以用文档生成工具来展示您的 API,用代码生成工具来自动生成各种编程语言的服务器端和客户端的代码,用自动测试工具进行测试等等。

参考文档:OpenAPI 规范 (中文版) https://openapi.apifox.cn/

Swagger

Swagger是一套围绕 Open API 规范构建的开源工具,可以帮助设计,构建,记录和使用 REST API。

Swagger工具包括的组件:

  • Swagger Editor :基于浏览器编辑器,可以在里面编写 Open API规范。类似 Markdown 具有实时预览描述文件的功能。
  • Swagger UI:将 Open API 规范呈现为交互式 API 文档。用可视化UI 展示描述文件。
  • Swagger Codegen:将 OpenAPI 规范生成为服务器存根和客户端库。通过 Swagger Codegen 可以将描述文件生成 html 格式和 cwiki 形式的接口文档,同时也可以生成多种言语的客户端和服务端代码。
  • Swagger Inspector:和 Swagger UI 有点类似,但是可以返回更多信息,也会保存请求的实际参数数据。
  • Swagger Hub:集成了上面所有项目的各个功能,你可以以项目和版本为单位,将你的描述文件上传到 Swagger Hub 中。在 SwaggerHub 中可以完成上面项目的所有工作,需要注册账号,分免费版和收费版。

使用 Swagger,就是把相关的信息存储在它定义的描述文件里面(yml 或 json 格式),再通过维护这个描述文件可以去更新接口文档,以及生成各端代码。

官方文档:https://swagger.io/

Springfox

Springfox是一套可以帮助Java开发者自动生成API文档的工具,它是基于Swagger 2.x基础上开发的,它遵循的是OpenAPI2.0(即Swagger2.0规范)。Swagger已经成为了RESTful API文档生态系统的事实标准,而Springfox是一个用于集成Swagger2.x到Spring应用程序中的库。而且Springfox提供了一些注解来描述API接口、参数和返回值,并根据这些信息生成Swagger UI界面,从而方便其他开发人员查看和使用您的API接口。

此外,Springfox还支持自动生成API文档和代码片段,简化了开发人员的工作量。除了集成Swagger 2.x,Springfox还提供了一些额外功能,例如自定义Swagger文档、API版本控制、请求验证等等。这些功能使得Springfox可以胜任各种类型和规模的应用程序,同时还可以提高代码质量和开发效率。

总之,Springfox是一个非常有用的工具,它可以帮助Java开发者快速、简单地集成Swagger2.x,并为他们的应用程序生成高质量的API文档。无论您开发的是大型企业应用程序还是小型服务,使用Springfox都能够提高团队的生产力和代码质量。

官方文档:https://springfox.github.io/springfox/

springdoc

SpringDoc是基于OpenAPI 3.0规范构建的,因此推荐在Spring Boot 2.4及以上版本中使用springdoc-openapi-ui库来集成Swagger3.x。在这些版本中,springdoc-openapi-ui库已被广泛应用,并且得到了社区的大力支持和推广。而在Spring Boot 2.3及其以下版本,可以使用springfox-boot-starter库来集成Swagger2.x。

SpringDoc有着更加先进的技术架构和更好的扩展性,使得其逐渐取代了springfox-boot-starter工具包,成为了当前Spring Boot生态中最受欢迎的API文档工具之一。同时springdoc-openapi-ui还拥有更为完善的开发文档和社区支持,从而吸引了越来越多的开发者加入到这个项目中。因此作为一个Spring Boot开发者,如果想要快速、方便地生成符合OpenAPI 3.0规范的接口文档,建议使用springdoc-openapi-ui这个优秀的工具。

官方文档:https://springdoc.org/

swagger2与swagger3常用注解对比

swagger2 swagger3 注解位置
@Api @Tag(name = “接口类描述”) Controller 类
@ApiOperation @Operation(summary =“接口方法描述”) Controller 方法
@ApiImplicitParams @Parameters Controller 方法
@ApiImplicitParam @Parameter(description=“参数描述”) Controller 方法的 @Parameters 里
@ApiParam @Parameter(description=“参数描述”) Controller 方法的参数上
@ApiIgnore @Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden -
@ApiModel @Schema DTO类上
@ApiModelProperty @Schema DTO属性上

实现步骤

引入maven依赖

pom.xml中添加springdoc-openapi-starter-webmvc-ui以及相关依赖。

<dependencies>
  <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
  </dependency>
  <!-- 项目中使用了spring-security时可以引入此依赖 -->
  <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-security</artifactId>
    <version>1.7.0</version>
  </dependency>
  <!-- 如果使用的是spring webflux而非spring-webmvc,则需要将springdoc-openapi-starter-webmvc-ui改为如下依赖 -->
  <!-- <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.3.0</version>
  </dependency> -->
</dependencies>

修改配置文件

application.yml中可以自定义api-docsswagger-ui的访问路径。

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html

设置api-docsswagger-ui访问权限

如果项目中启用了权限控制,需要合理设置api-docsswagger-ui相关资源的访问权限。比如笔者使用的spring-security,将api-docsswagger-ui相关资源设置为允许匿名访问,不需要认证授权。

@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        // 将api-docs和swagger-ui相关资源设置为允许匿名访问
        http.authorizeHttpRequests((authorizationManagerRequestMatcherRegistry) -> {
			authorizationManagerRequestMatcherRegistry.requestMatchers("/v3/api-docs").permitAll();
			authorizationManagerRequestMatcherRegistry.requestMatchers("/v3/api-docs/**").permitAll();
			authorizationManagerRequestMatcherRegistry.requestMatchers("/swagger-ui.html").permitAll();
			authorizationManagerRequestMatcherRegistry.requestMatchers("/swagger-ui/**").permitAll();
        
            // 其余资源登录后方可访问
            authorizationManagerRequestMatcherRegistry.anyRequest().authenticated();
        });
    	
        // 其余spring security配置已省略
        // ...
        
        return http.build();
    }
}

定义springdoc配置类

@Configuration
public class SpringDocConfig {
    /**
     * 一个自定义的 OpenAPI 对象
     *
     * @return 一个自定义的 OpenAPI 对象
     */
    @Bean
    public OpenAPI customOpenApi() {
        return new OpenAPI()
        .components(new Components()
                    // 设置 spring security jwt accessToken 认证的请求头 Authorization: Bearer xxx.xxx.xxx
                    .addSecuritySchemes("openApiSecurityScheme", new SecurityScheme()
                                        .type(SecurityScheme.Type.HTTP)
                                        .bearerFormat("JWT")
                                        .in(SecurityScheme.In.HEADER)
                                        .name("Authorization")
                                        .scheme("Bearer")))
        // 设置标题、版本等信息
        .info(new Info()
              .title("Fast Alden权限管理系统")
              .version("0.0.1-SNAPSHOT")
              .description("")
              .license(new License()
                       .name("Apache 2.0")
                       .url("https://www.apache.org/licenses/LICENSE-2.0.html")));
    }
}

在上述代码中定义了一个key为openApiSecuritySchemeSecuritySchemes,在后续章节的Controller类中使用。

修改Controller类和实体类

在Controller类和实体类中添加swagger相关注解。

  • @Tag 用于标识controller
  • @Operation 用于标识方法
  • @Schema 用于标识实体类和实体类的属性
  • @ApiResponse 用于标识请求的响应
  • @Parameters和@Parameter 用于标识请求参数,@Parameter的name需要和变量的命名一致,@Parameter要放到函数形参前面

以下代码中@Operation注解通过security属性指定认证方式,openApiSecurityScheme已在上文springdoc配置类中声明。

  1. SysUserController.java
// SysUserController.java
@Tag(name = "SysUserController", description = "后台用户管理")
@RestController
@RequestMapping("/user")
public class SysUserController {
    @Resource
    private SysUserService userService;

    @Operation(summary = "根据ID查询", security = @SecurityRequirement(name = "openApiSecurityScheme"))
    @GetMapping("/retrieve/{id}")
    public SysUser retrieve(@PathVariable("id") Long id) {
        return userService.retrieve(id);
    }

    @Operation(summary = "创建用户", security = @SecurityRequirement(name = "openApiSecurityScheme"))
    @PostMapping("/create")
    public Long create(@RequestBody SysUser user) {
        return userService.create(user).getId();
    }

    @Operation(summary = "修改用户", security = @SecurityRequirement(name = "openApiSecurityScheme"))
    @PutMapping("/update")
    public void update(@RequestBody SysUser user) {
        userService.update(user);
    }

    @Operation(summary = "删除用户", security = @SecurityRequirement(name = "openApiSecurityScheme"))
    @DeleteMapping("/remove")
    public void remove(@RequestParam("ids") List<Long> ids) {
        userService.remove(ids);
    }
}

  1. SysUser.java
// SysUser.java
/**
 * 用户实体类
 */
@Getter
@Setter
@Schema(description = "用户")
public class SysUser {
    @Schema(description = "用户ID")
    private Long id;

    @Schema(description = "用户名")
    private String username;

    @Schema(description = "密码")
    private String password;

    @Schema(description = "电话")
    private String phone;

    @Schema(description = "个人介绍")
    private String introduce;

    @Schema(description = "所属部门ID")
    private Long departmentId;
}

查看效果

  1. 访问 http://localhost:8080/v3/api-docs可获取JSON格式的API文档。

image

  1. 访问 http://localhost:8080/swagger-ui.html可直接在线测试API,在Authorize弹窗中可以填入token用于模拟在线用户。

image

image

总结

本文简单介绍了一下OpenAPI、Swagger、Springfox和SpringDoc的相关概念,以及详细介绍了SpringBoot3整合SpringDoc的过程,如有错误,还望批评指正。

在后续实践中我也是及时更新自己的学习心得和经验总结,希望与诸位看官一起进步。

标签:Java21,swagger,SpringSecurity,API,ui,springdoc,文档,Swagger
From: https://www.cnblogs.com/breezefaith/p/17998698

相关文章

  • Java21 + SpringBoot3整合Redis,使用Lettuce连接池,推荐连接池参数配置,封装Redis操作
    目录前言相关技术简介Redis实现步骤引入maven依赖修改配置文件定义Redis配置类定义Redis服务类,封装Redis常用操作使用Redis服务类总结前言近日心血来潮想做一个开源项目,目标是做一款可以适配多端、功能完备的模板工程,包含后台管理系统和前台系统,开发者基于此项目进行裁剪和扩展......
  • SpringSecurity-手机号+短信验证码登陆
    与验证码登录逻辑是不一样的,所以不能使用SpringSecurity默认提供的那套逻辑;需要自个去写一个自定义身份认证逻辑短信验证码生成生成验证码短信验证码类ValidateCode是父类,ImageCode子类publicclassValidateCode{privateStringcode;/***过期时间......
  • Java21 + SpringBoot3集成easy-captcha实现验证码显示和登录校验
    目录前言相关技术简介easy-captcha实现步骤引入maven依赖定义实体类定义登录服务类定义登录控制器前端登录页面实现测试和验证总结附录使用Session缓存验证码前端登录页面实现代码前言近日心血来潮想做一个开源项目,目标是做一款可以适配多端、功能完备的模板工程,包含后台管理系......
  • springboot整合springSecurity入门案例(实现登录,记住我等常用标签使用)
    一,整合进依赖每个依赖都标了注释,大家可以按照自己需要的来添加,置于配置问件啥的,大家可以参考springboot+mybatisplus+redis整合(附上脚手架完整代码)<!--主要就是加了这个依赖--><dependency><groupId>org.springframework.security</groupId><artifact......
  • SpringSecurity-记得我
    原理在用户发送认证请求之后,或调用我们之前说过的usernamePasswordAuthenticationFilter这个过滤器,认证成功之后会调用一个RemeberMeService服务;负责针对每一用户生成一个Token,然后将token写入到浏览器的Cookie里面,同时会使用:TokenRepository将这个token写入数据库中。将Toke......
  • Java21 + SpringBoot3集成WebSocket
    目录前言相关技术简介什么是WebSocketWebSocket的原理WebSocket与HTTP协议的关系WebSocket优点WebSocket应用场景实现方式添加maven依赖添加WebSocket配置类,定义ServerEndpointExporterBean定义WebSocketEndpoint前端创建WebSocket对象总结前言近日心血来潮想做一个开源项目,目......
  • SpringSecurity-图片验证码
    图片验证码生成Core模块封装验证码类publicclassImageCode{    privateBufferedImageimage;    /**     *code是一个随机数,图片是根据随机数生成的,     *存放到session里面,后面用户提交登录请求时候要去验证的     */    private......
  • SpringSecurity-认证流程源码级详解
    自定义用户认证逻辑处理用户信息获取逻辑:UserDetailsService处理用户校验逻辑:UserDetails处理密码加密解密:PasswordEncoder认证处理流程以表单认证为例:从发起认证请求到认证过滤器,接着认证成功后,响应从认证过滤器返回的整个过程。SpringSecurity做了什么,设计到了哪些类?他......
  • SpringSecurity系列,第四章:源码分析
    源码分析SpringSecurity的核心功能即为:认证(Authentication)、授权(Authorization)一、概览1、在SpringSecurity中,用户的认证信息主要由Authentication的实现类来保存,Authentication接口定义如下:【保存用户认证信息】publicinterfaceAuthenticationextendsPrin......
  • SpringSecurity表单认证(二)
    用户名+密码系统默认登录用户名:user密码每次服务启动后随机生成密码用户信息获取原理(数据库获取)实现该接口,security默认自动生成密码关闭。框架源码:packageorg.springframework.security.core.userdetails;publicinterfaceUserDetailsService{UserDetailsloa......