背景

Spring boot 曾经更新到了 v2.6+，如果你还在应用Springfox提供swagger接口文档，你会遇到以下谬误：

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException    ...Caused by: java.lang.NullPointerException: null    at springfox.documentation.spring.web.WebMvcPatternsRequestConditionWrapper.getPatterns(WebMvcPatternsRequestConditionWrapper.java:56) ~[springfox-spring-webmvc-3.0.0.jar:3.0.0]    at springfox.documentation.RequestHandler.sortedPaths(RequestHandler.java:113) ~[springfox-core-3.0.0.jar:3.0.0]

Springfox的更新速度太慢了，为了适配新版本Spring boot，将其替换为SpringDoc是个更优的抉择。

配置集成 SpringDoc 实现 swagger接口文档

步骤1. pom中引入SpringDoc依赖

<dependency>    <groupId>org.springdoc</groupId>    <artifactId>springdoc-openapi-ui</artifactId>    <version>1.5.12</version></dependency>

步骤2. 增加配置类

// 示例配置类@Configurationpublic class OpenApiConfig {    @Bean    public OpenAPI initOpenAPI() {        return new OpenAPI().info(            new Info().title("My Project API").description("OpenAPI").version("v1.0")        );    }}

步骤1&2为swagger的失常配置，如果零碎有接口URL的安全检查，须要将以下接口配置为容许匿名拜访，以使swagger相干url能够拜访到。
步骤3. 设置swagger相干的匿名url配置，使swagger不被拦挡， 如下：

/swagger**/**/v3/**

如果应用了diboot-IAM组件，相干配置示例如下:

diboot.iam.anon-urls=/swagger**/**,/v3/**

swagger3 相干注解阐明

加在Controller类及办法上的注解 （@Tag & @Operation）：

import io.swagger.v3.oas.annotations.tags.Tag;import io.swagger.v3.oas.annotations.Operation;//...@Tag(name = "用户接口", description = "用户相干CRUD接口")public class UserController{        @Operation(summary = "获取用户列表数据")    @GetMapping("/list")    public JsonResult getViewObjectListMapping() throws Exception{        //...    }}

加在Entity/Model类及属性上的注解 （@Schema）：

import io.swagger.v3.oas.annotations.media.Schema;import java.io.Serializable;@Schema(name = "用户", description = "用户实体定义")public class User implements Serializable {    private static final long serialVersionUID = 111222L;    /**     * 名称      */    @Schema(description = "名称", required = true, example = "张三")    private String name;}

swagger 接口文档拜访入口地址:

  • swagger接口文档入口地址: /{contextPath}/swagger-ui.html

示例成果如图：

其余罕用配置

指定接口包门路

增加以下配置，指定接口扫描package包门路：

springdoc.packages-to-scan=com.example

生产环境禁用swagger

增加以下配置，敞开接口文档：

springdoc.api-docs.enabled=false

diboot 简略高效的低代码开发框架