Spring Doc OpenAPI3.0 拋棄SpringFox擁抱SpringDoc

這篇具有很好參考價值的文章主要介紹了Spring Doc OpenAPI3.0 拋棄SpringFox擁抱SpringDoc。希望對大家有所幫助。如果存在錯誤或未考慮完全的地方，請大家不吝賜教，您也可以點擊"舉報違法"按鈕提交疑問。

Spring Doc

1 簡介

SpringDoc是SpringBoot 的API文檔工具。官網：https://springdoc.org/

在使用SpringBoot 2.6以前去創(chuàng)建API文檔工具一般會采用SpringFox提供的Swagger庫，但是由于SpringBoot版本的不斷升級和SpringFox擺爛不更新，導致了SpringBoot2.6之后的項目無法使用SpringFox去生成API文檔，或者可以使用但是有很多的bug。

SpringDoc是一款可以結合SpringBoot使用API文檔生成工具，基于OpenAPI 3，而且項目維護和社區(qū)都在不斷更新，不僅支持SpringMVC，而且還支持Spring WebFlux項目。

下圖為SpringDoc的架構圖的總體概述。
springdoc-openapi-ui,spring boot,java,后端,spring,java,spring boot

2 基本使用

2.1 新建項目并導入maven

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

2.2 使用注解標記接口

2.2.1 常用注解

注解	描述
@Tag	標記在接口類上，用來設置 Controller 的名稱和描述
@Parameter/@Parameters	用來設置請求參數的描述
@Operation	對接口方法的描述，可以設置接口的名稱
@ApiResponse/@ApiResponses	用來配置響應
@Schema	標記在模型（model）類上或類的屬性上，進行標注解釋。

2.2.2 測試Controler Demo

TestController

package org.example.controller.test;
/**
 * 省略import
 */
@Tag(name = "測試接口", description = "定義測試接口")
@RestController
@RequestMapping("/test")
public class TestController {
    @Operation(summary = "get測試接口", description = "返回id")
    @Parameter(name = "id", description = "參數ID", example = "123456")
    @ApiResponse(responseCode = "403", description = "無權限")
    @GetMapping("/get")
    public Map<String, Object> get(@Parameter(description = "id") String id) {
        Map<String, Object> res = new HashMap<>(1);
        res.put("id", id);
        return res;
    }
}

UserController

package org.example.controller.user;
/**
 * 省略import
 */
@Tag(name = "用戶接口", description = "定義用戶接口")
@RestController
@RequestMapping("/user")
public class UserController {
    @Operation(summary = "post測試接口", description = "返回username")
    @Parameter(name = "username", description = "參數username", example = "username")
    @ApiResponse(responseCode = "403", description = "無權限")
    @PostMapping("/post")
    public Map<String, Object> get(@Parameter(description = "用戶名") String username) {
        Map<String, Object> res = new HashMap<>(1);
        res.put("username", username);
        return res;
    }
}

2.3 編寫SpringDocConfig

2.3.1 常用springdoc的配置

package org.example.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springdoc.core.GroupedOpenApi;
import org.springdoc.core.customizers.OpenApiCustomiser;
import org.springdoc.core.customizers.OperationCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * @author zhong
 */
@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI defaultOpenAPI() {
//        return new OpenAPI()
//                .info(info())
//                .externalDocs(documentation())
//                .components(new Components().addSecuritySchemes("Authorization", new SecurityScheme().name("認證").type(SecurityScheme.Type.HTTP)
//                        .description("JWT認證").scheme("bearer").bearerFormat("JWT")));


        return new OpenAPI().
                info(info())
                .externalDocs(documentation());
    }

    public Info info() {
        return new Info()
                .title("SpringDoc OpenApi")
                .version("V1.0.0")
                .description("測試spring doc open api")
                .license(new License().name("許可證名稱").url("許可證地址"))
                .contact(new Contact().name("聯系人").url("聯想人鏈接"))
                .summary("概要");
    }

    public ExternalDocumentation documentation() {
        return new ExternalDocumentation().description("文檔描述").url("文檔地址");
    }

    @Bean
    public GroupedOpenApi testApi() {
        return GroupedOpenApi.builder()
                .displayName("測試接口")
                .group("test")
                .packagesToScan("org.example.controller.test")
                .build();
    }

    @Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
                .displayName("用戶接口")
                .group("user")
                .packagesToScan("org.example.controller.user")
                .addOpenApiCustomiser(openApiCustomiser())
                .addOperationCustomizer(operationCustomizer())
                .build();
    }

    public OpenApiCustomiser openApiCustomiser() {
        return api ->
                api.components(new Components()
                        .addSecuritySchemes("Authorization", new SecurityScheme().name("認證").type(SecurityScheme.Type.HTTP)
                                .description("JWT認證").scheme("bearer").bearerFormat("JWT"))
                );
    }

    public OperationCustomizer operationCustomizer() {
        return (operation, handlerMethod) -> {
            operation.addSecurityItem(new SecurityRequirement().addList("Authorization"));
            return operation;
        };
    }
}

2.3.2 關于接口鑒權問題（jwt方式）

如以上配置所示，user接口設置了鑒權設置

對一個分組的接口添加鑒權的方式

@Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
                .displayName("用戶接口")
                .group("user")
                .packagesToScan("org.example.controller.user")
                .addOpenApiCustomiser(openApiCustomiser())
                .addOperationCustomizer(operationCustomizer())
                .build();
}
public OpenApiCustomiser openApiCustomiser() {
    return api ->
            api.components(new Components()
                    .addSecuritySchemes("Authorization", new SecurityScheme().name("認證").type(SecurityScheme.Type.HTTP)
                            .description("JWT認證").scheme("bearer").bearerFormat("JWT"))
            );
}

public OperationCustomizer operationCustomizer() {
    return (operation, handlerMethod) -> {
        operation.addSecurityItem(new SecurityRequirement().addList("Authorization"));
        return operation;
    };
}

如果嫌麻煩，可以設置全局設置

例如配置代碼注釋的部分添加全局配置

 @Bean
    public OpenAPI defaultOpenAPI() {
        return new OpenAPI()
                .info(info())
                .externalDocs(documentation())
                .components(new Components().addSecuritySchemes("Authorization", new SecurityScheme().name("認證").type(SecurityScheme.Type.HTTP)
                        .description("JWT認證").scheme("bearer").bearerFormat("JWT")));

    }

2.4 啟動效果

訪問http://localhost:8080/swagger-ui/index.html

springdoc-openapi-ui,spring boot,java,后端,spring,java,spring boot

2.5 一些application的配置說明

2.5.1 springdoc-openapi 核心屬性

官方鏈接：https://springdoc.org/#springdoc-openapi-core-properties

參數名稱	默認值	描述
springdoc.api-docs.path	`/v3/api-docs`	`String`, 用于 Json 格式的 OpenAPI 文檔的自定義路徑。
springdoc.api-docs.enabled	`true`	`Boolean`. 禁用 springdoc-openapi 端點（默認為 /v3/api-docs）。
springdoc.packages-to-scan	`*`	`List of Strings`.要掃描的包列表（逗號分隔）
springdoc.paths-to-match	`/*`	`List of Strings`.要匹配的路徑列表（逗號分隔）
springdoc.produces-to-match	`/*`	`List of Strings`.The list of produces mediaTypes to match (逗號分隔)
springdoc.headers-to-match	`/*`	`List of Strings`.要匹配的標題列表（逗號分隔）
springdoc.consumes-to-match	`/*`	`List of Strings`.要匹配的消耗媒體類型列表（逗號分隔）
springdoc.paths-to-exclude		`List of Strings`.要排除的路徑列表（逗號分隔）
springdoc.packages-to-exclude		`List of Strings`.要排除的包列表（逗號分隔）
springdoc.default-consumes-media-type	`application/json`	`String`. 默認使用媒體類型。
springdoc.default-produces-media-type	`/`	`String`.默認產生媒體類型。
springdoc.cache.disabled	`false`	`Boolean`. 禁用計算 OpenAPI 的 springdoc-openapi 緩存。
springdoc.show-actuator	`false`	`Boolean`. 顯示執(zhí)行器端點。
springdoc.auto-tag-class	`true`	`Boolean`. 禁用 springdoc-openapi 自動標簽。
springdoc.model-and-view-allowed	`false`	`Boolean`. 允許帶有 ModelAndView 返回的 RestControllers 出現在 OpenAPI 描述中。
springdoc.override-with-generic-response	`true`	`Boolean`. 當為 true 時，自動將 @ControllerAdvice 響應添加到所有生成的響應中。
springdoc.api-docs.groups.enabled	`true`	`Boolean`. 禁用 springdoc-openapi 組。
springdoc.group-configs[0].group		`String`.群名
springdoc.group-configs[0].display-name		`String`.組的顯示名稱。
springdoc.group-configs[0].packages-to-scan	`*`	`List of Strings`.要掃描組的包列表（逗號分隔）
springdoc.group-configs[0].paths-to-match	`/*`	`List of Strings`.組匹配的路徑列表（逗號分隔）
springdoc.group-configs[0].paths-to-exclude	``	`List of Strings`.要為組排除的路徑列表（逗號分隔）
springdoc.group-configs[0].packages-to-exclude		`List of Strings`.要排除的包列表（逗號分隔）
springdoc.group-configs[0].produces-to-match	`/*`	`List of Strings`.The list of produces mediaTypes to match (逗號分隔)
springdoc.group-configs[0].consumes-to-match	`/*`	`List of Strings`.要匹配的消耗媒體類型列表（逗號分隔）
springdoc.group-configs[0].headers-to-match	`/*`	`List of Strings`.要匹配的標題列表（逗號分隔）
springdoc.webjars.prefix	`/webjars`	`String`, 把swagger-ui的URL可見的webjars前綴換成spring-webflux。
springdoc.api-docs.resolve-schema-properties	`false`	`Boolean`. 在@Schema 上啟用屬性解析器（名稱、標題和描述）。
springdoc.remove-broken-reference-definitions	`true`	`Boolean`. 禁用刪除損壞的引用定義。
springdoc.writer-with-default-pretty-printer	`false`	`Boolean`. 啟用 OpenApi 規(guī)范的漂亮打印。
springdoc.model-converters.deprecating-converter.enabled	`true`	`Boolean`. 禁用棄用模型轉換器。
springdoc.model-converters.polymorphic-converter.enabled	`true`	`Boolean`. 禁用多態(tài)模型轉換器。
springdoc.model-converters.pageable-converter.enabled	`true`	`Boolean`. 禁用可分頁模型轉換器。
springdoc.model-converters.sort-converter.enabled	`true`	`Boolean`. 禁用排序轉換器。
springdoc.use-fqn	`false`	`Boolean`. 啟用完全限定名稱。
springdoc.show-endpoint	`false`	`Boolean`. 使 spring security 登錄端點可見。
springdoc.pre-loading-enabled	`false`	`Boolean`. 預加載設置以在應用程序啟動時加載 OpenAPI。
springdoc.writer-with-order-by-keys	`false`	`Boolean`. 啟用確定性/字母順序。
springdoc.use-management-port	`false`	`Boolean`. 在執(zhí)行器管理端口上公開 swagger-ui。
springdoc.disable-i18n	`false`	`Boolean`. 使用 i18n 禁用自動翻譯。
springdoc.show-spring-cloud-functions	`true`	`Boolean`. 顯示 spring-cloud-function Web 端點。
springdoc.api-docs.version	`openapi_3_0`	`String`. 選擇`OpenAPI 3.0`或`OpenAPI 3.1`（使用值`OPENAPI_3_1`）。
springdoc.default-flat-param-object	`false`	`Boolean`. 默認展平參數。
springdoc.default-support-form-data	`false`	`Boolean`. 指定api接受表單數據時默認設置參數為表單數據。
springdoc.nullable-request-parameter-enabled	`true`	`Boolean`. 在 Kotlin 中默認啟用對可空請求參數的支持。
springdoc.show-oauth2-endpoints	`false`	`Boolean`. 使 spring security oauth2-endpoint 可見。

2.5.2 swagger-ui核心屬性

官方鏈接https://springdoc.org/#swagger-ui-properties

參數名稱	默認值	描述
springdoc.swagger-ui.path	`/swagger-ui.html`	`String`, 用于 swagger-ui HTML 文檔的自定義路徑。
springdoc.swagger-ui.enabled	`true`	`Boolean`. 禁用 swagger-ui 端點（默認為 /swagger-ui.html）。
springdoc.swagger-ui.configUrl	`/v3/api-docs/swagger-config`	`String`. 從中獲取外部配置文檔的 URL。

2 從SpringFox遷移

刪除 springfox 和 swagger 2 依賴項。添加springdoc-openapi-ui依賴項。

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

用 swagger 3 注釋替換 swagger 2 注釋（它已經包含在springdoc-openapi-ui依賴項中）。swagger 3 注釋的包是io.swagger.v3.oas.annotations.
- @Api→@Tag
- @ApiIgnore→@Parameter(hidden = true)或@Operation(hidden = true)或@Hidden
- @ApiImplicitParam→@Parameter
- @ApiImplicitParams→@Parameters
- @ApiModel→@Schema
- @ApiModelProperty(hidden = true)→@Schema(accessMode = READ_ONLY)
- @ApiModelProperty→@Schema
- @ApiOperation(value = "foo", notes = "bar")→@Operation(summary = "foo", description = "bar")
- @ApiParam→@Parameter
- @ApiResponse(code = 404, message = "foo")→@ApiResponse(responseCode = "404", description = "foo")
如果您使用一個對象來捕獲多個請求查詢參數，請注釋該方法參數@ParameterObject
此步驟是可選的：僅當您有多個 Docketbeans 時才用GroupedOpenApibeans 替換它們。

前：

  @Bean
  public Docket publicApi() {
      return new Docket(DocumentationType.SWAGGER_2)
              .select()
              .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
              .paths(PathSelectors.regex("/public.*"))
              .build()
              .groupName("springshop-public")
              .apiInfo(apiInfo());
  }

  @Bean
  public Docket adminApi() {
      return new Docket(DocumentationType.SWAGGER_2)
              .select()
              .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin"))
              .paths(PathSelectors.regex("/admin.*"))
              .apis(RequestHandlerSelectors.withMethodAnnotation(Admin.class))
              .build()
              .groupName("springshop-admin")
              .apiInfo(apiInfo());
  }

現在：

  @Bean
  public GroupedOpenApi publicApi() {
      return GroupedOpenApi.builder()
              .group("springshop-public")
              .pathsToMatch("/public/**")
              .build();
  }
  @Bean
  public GroupedOpenApi adminApi() {
      return GroupedOpenApi.builder()
              .group("springshop-admin")
              .pathsToMatch("/admin/**")
              .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
              .build();
  }

如果你只有一個 Docket?- 刪除它并添加屬性到你的application.properties：

springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**

添加OpenAPI類型的bean。參見示例：

  @Bean
  public OpenAPI springShopOpenAPI() {
      return new OpenAPI()
              .info(new Info().title("SpringShop API")
              .description("Spring shop sample application")
              .version("v0.0.1")
              .license(new License().name("Apache 2.0").url("http://springdoc.org")))
              .externalDocs(new ExternalDocumentation()
              .description("SpringShop Wiki Documentation")
              .url("https://springshop.wiki.github.org/docs"));
  }

3 使用 knife4j美化

springdoc-openapi-ui,spring boot,java,后端,spring,java,spring boot

3.1 使用方法

Knife4j是一個集Swagger2 和 OpenAPI3為一體的增強解決方案。

官網：https://doc.xiaominfo.com/

首先，引用Knife4j的starter,Maven坐標如下：

<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
	<version>4.1.0</version>
</dependency>

然后刪除之前的springdoc-openapi-ui

springdoc-openapi-ui,spring boot,java,后端,spring,java,spring boot

3.2 常用配置項

官方說明地址：https://doc.xiaominfo.com/docs/features/enhance文章來源地址http://www.zghlxwxcb.cn/news/detail-763176.html

## knife4j的增強配置，不需要增強可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn
    enable-home-custom: true
    home-custom-path: classpath:markdown/api-home.md
    enable-footer-custom: true
    footer-custom-content: 系統(tǒng)文檔