乐趣区

关于swagger:Spring-Boot-集成-SpringDoc-Swagger-3

jiezi

背景

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. 增加配置类 

// 示例配置类
@Configuration
public 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 简略高效的低代码开发框架

退出移动版