Spring Boot 整合 SpringDoc Swagger 3

JerryMa發表於2021-11-23
Spring BootSwagger

背景

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

示例效果如圖：
swagger v3 介面文件效果

其他常用配置

指定介面包路徑

新增以下配置，指定介面掃描package包路徑：

springdoc.packages-to-scan=com.example

生產環境禁用swagger

新增以下配置，關閉介面文件：

springdoc.api-docs.enabled=false

diboot 簡單高效的低程式碼開發框架

相關文章