随手记录第十四话 -- 在 Spring Boot 3.2.3 中使用 springdoc-openapi-starter-webmvc-ui

项目升级到JDK21后，SpringBoot版本也到了3.2.3，之前的Swagger-ui不在支持了，找了其他的一直忘记记录了，这里记录一下。

1.引言

随着 Spring Boot 版本的更新，一些依赖和配置也发生了变化。在 Spring Boot 3.2.3 中，原来常用的 Swagger-UI 不再直接支持，我们需要切换到 springdoc-openapi-starter-webmvc-ui 来实现类似的 API 文档功能。

2.添加依赖

基于Springboot3.2.3，引入pom依赖

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.3</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>

<!-- Swagger UI 相关 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

3.配置类

你可以创建一个配置类来进一步定制 OpenAPI 的相关属性，比如文档标题、版本等。

/**
 * 创建一个公共类
 * api页面 http://127.0.0.1:8080/swagger-ui/index.html
 */
@SecurityScheme(name = "Authorization", type = SecuritySchemeType.HTTP, scheme = "bearer", in = SecuritySchemeIn.HEADER)
public abstract class SwaggerConf {


    @Bean
    public OpenAPI createOpenApi() {
        return new OpenAPI()
                .info(apiInfo())
                //设置授权信息
                .security(List.of(new SecurityRequirement().addList("Authorization")))
                //引入其他文档
//                .externalDocs(new ExternalDocumentation().description("百度一下")
//                        .url("http://www.baido.com"))
                ;
    }
    
    public abstract Info apiInfo();

    //分组
    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("api")
                .pathsToMatch("/api/**")
                .build();
    }

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("admin")
                .pathsToMatch("/admin/**")
                .build();
    }
}

然后其他服务实现

@Profile({"dev", "test"})
@Configuration
public class SwaggerConfig extends SwaggerConf {

    @Override
    public Info apiInfo() {
        return new Info()
                .title("一款 xxx 业务接口文档")
                .description("xxx业务处理")
                .version("1.0");
    }
}

4.Java代码实现

@Tag(name = "钱包app相关接口")
@RestController
@RequestMapping("/api/app")
public class WalletController {
	
	 @Operation(summary = "获取钱包初始化配置", description = "获取配置")
    @AnonymousGetMapping("/homeConfig")
    public ApiResultVO<JSONObject> getHomeConfig(@RequestParam(required = false) Long fromId) {
		.....    
	}
}

//返回bean注解
@NoArgsConstructor
@Data
@Schema(name = "ApiResult", description = "REST接口标准返回值 View Model")
public class ApiResultVO<T> implements Serializable {

    /**
     * 返回码
     */
    @Schema(title ="REST接口返回码")
    private Integer code;

    /**
     * 返回描述
     */
    @Schema(title ="REST接口返回消息")
    private String message;
}

如果需要使用鉴权头部，需要用下面这个注解

@SecurityScheme(name = "Authorization", type = SecuritySchemeType.HTTP, scheme = "bearer", in = SecuritySchemeIn.HEADER)

5.启动应用

地址与原来的有点区别 http://127.0.0.1:8080/swagger-ui/index.html

实体类截图

6.总结

通过使用 springdoc-openapi-starter-webmvc-ui ，我们可以在 Spring Boot 3.2.3 中继续方便地生成和展示 API 文档，帮助我们更好地理解和管理项目中的接口。在实际应用中，可以根据需要进行更深入的定制和优化。
希望这篇文章对你顺利过渡到新的 API 文档工具提供帮助，让你在开发过程中能够更好地与 API 进行交互和文档化。

上一篇：随手记录第十三话 – 关于Python自动化部署神器fabric的应用与差异
下一篇：随手记录第十五话 – xxxx

烹羊宰牛且为乐，会须一饮三百杯