springdoc-openapi 簡介

springdoc-openapijava庫有助于使用 spring boot 項(xiàng)目自動生成 API 文檔。 springdoc-openapi通過在運(yùn)行時檢查應(yīng)用程序以根據(jù) spring 配置、類結(jié)構(gòu)和各種注釋推斷 API 語義來工作。

自動生成 JSON/YAML 和 HTML 格式 API 的文檔?？梢允褂?swagger-api 注釋通過注釋來完成此文檔。

該庫支持：

• OpenAPI3

• SpringBoot (v1, v2 and v3)

• JSR-303, specifically for @NotNull, @Min, @Max, and @Size.

• Swagger-ui

• OAuth 2

• GraalVM 原生鏡像

為什么使用 springdoc-openapi??

由于之前項(xiàng)目一直使用的是springfox3.0來集成swagger管理API接口文檔，但目前springfox已經(jīng)停止維護(hù)了。最近在升級底層框架時看到spring官方推薦使用springdoc，在自己一步一步查找相關(guān)資料時，發(fā)現(xiàn)國內(nèi)對于這塊的參考資料較少，也不全面。故寫此篇文章來幫助大家快速集成。

Knife4j簡介

Knife4j是一個集Swagger2和OpenAPI3為一體的增強(qiáng)解決方案。

開始集成

Maven引入

首先在maven里引入springdoc-openapi：

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>1.6.15</version></dependency>復(fù)制代碼

注釋的區(qū)別

這里需要注意，我們要用swagger3注釋替換swagger2注釋（它已經(jīng)包含在springdoc-openapi-ui依賴項(xiàng)中）。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")復(fù)制代碼

以下舉幾個簡單的??：

Controller：

@Tag(name = "用戶接口")@RestController@RequestMapping("sys/user")publicclassSysUserController {

    @Resourceprivate ISysUserService sysUserService;

    @Operation(summary = "分頁查詢")@GetMapping("page")public AjaxResult queryPage(SysUserPageDTO dto) {
        PageInfopage= sysUserService.queryPage(dto);
        return AjaxResult.success(page);
    }

    @Operation(summary = "詳情")@GetMapping("{id}")public AjaxResult queryInfo(@PathVariable Long id) {
        SysUserDTOdto= sysUserService.queryById(id);
        return AjaxResult.success(dto);
    }

    @Operation(summary = "新增")@PostMappingpublic AjaxResult save(@RequestBody SysUserDTO dto) {
        Longid= sysUserService.saveInfo(dto);
        return AjaxResult.success(id);
    }
}
復(fù)制代碼

DTO:

@Schema(description = "用戶 數(shù)據(jù)傳輸對象")@Data@Accessors(chain = true)publicclassSysUserDTOimplementsSerializable {

    @Schema(description = "ID")private Long id;

    @Schema(description = "用戶名")private String userName;

    @Schema(description = "真實(shí)姓名")private String realName;

    @Schema(description = "密碼")private String password;

    @Schema(description = "性別（0男，1女）")private Integer sex;

    @Schema(description = "電話號碼")private String phone;

    @Schema(description = "狀態(tài)（0停用，1正常）")private Integer status;
}
復(fù)制代碼

配置

配置文件，更多配置請看：springdoc 核心配置

springdoc:api-docs:# 是否開啟接口文檔enabled:trueswagger-ui:# 持久化認(rèn)證數(shù)據(jù)，如果設(shè)置為 true，它會保留授權(quán)數(shù)據(jù)并且不會在瀏覽器關(guān)閉/刷新時丟失persistAuthorization:true復(fù)制代碼

配置文檔:

? 這里我更推薦將文檔標(biāo)題、作者等信息寫到application里，然后通過@ConfigurationProperties引入，會更優(yōu)雅??

@Configuration@AutoConfigureBefore(SpringDocConfiguration.class)publicclassOpenApiConfig {

    privatestaticfinalStringTOKEN_HEADER="Authorization";

    @Beanpublic OpenAPI openApi() {
        // 針對 knife4j（增強(qiáng)UI），這里添加全局請求頭（addParameters）無效，只能按組添加，待官方解決returnnewOpenAPI()
                .components(
                        newComponents().addSecuritySchemes(TOKEN_HEADER,
                                newSecurityScheme()
                                        .type(SecurityScheme.Type.APIKEY)
                                        // 這里配置 bearer 后，你的請求里會自動在 token 前加上 Bearer
                                        .scheme("bearer")
                                        .bearerFormat("JWT")
                        ).addParameters(TOKEN_HEADER,
                                newParameter()
                                        .in("header")
                                        .schema(newStringSchema())
                                        .name(tokenHeader)
                        ))
                .info(
                        newInfo()
                                .title("文檔標(biāo)題")
                                .description("文檔描述")
                                .contact(newContact().name("作者").email("郵箱").url("可以寫你的博客地址或不填"))
                                // 參考 Apache 2.0 許可及地址，你可以不配此項(xiàng)
                                .license(newLicense().name("Apache 2.0").url("https://www.apache.org/licenses/LICENSE-2.0.html"))
                                .version("0.1")
                )
                // 引入外部的文檔，我這里引得是 springdoc 官方文檔地址，你可以不配此項(xiàng)
                .externalDocs(newExternalDocumentation()
                        .description("SpringDoc Full Documentation")
                        .url("https://springdoc.org/")
                );
    }

    /**
     * GroupedOpenApi 是對接口文檔分組，類似于 swagger 的 Docket
     * 
     * @return
     */@Beanpublic GroupedOpenApi authApi() {
        return GroupedOpenApi.builder()
                // 組名
                .group("認(rèn)證接口")
                // 掃描的路徑，支持通配符
                .pathsToMatch("/login")
                // 掃描的包
                .packagesToScan("com.demo.controller.auth")
                .build();
    }
    
    @Beanpublic GroupedOpenApi sysApi() {
        return GroupedOpenApi.builder()
                .group("系統(tǒng)接口")
                .pathsToMatch("/sys/**")
                // 添加自定義配置，這里添加了一個用戶認(rèn)證的 header，否則 knife4j 里會沒有 header
                .addOperationCustomizer((operation, handlerMethod) -> operation.security(
                        Collections.singletonList(newSecurityRequirement().addList(TOKEN_HEADER)))
                )
                .build();
    }
}
復(fù)制代碼

訪問文檔

配置完成之后，就可以訪問文檔地址：http://localhost:${port}/${context-path}/swagger-ui/html.index

? 如果你加入了攔截器或引入了spring-security等權(quán)限框架，需要放通文檔地址及靜態(tài)資源：

- /**/*.html
- /**/*.css
- /**/*.js
- /**/api-docs/**
復(fù)制代碼

至此一個簡單的接口文檔就生成了，是不是很簡單??

集成knife4j

Maven引入

在maven里引入knife4j

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-spring-boot-starter</artifactId><version>4.0.0</version></dependency>復(fù)制代碼

? 如果你使用的是SpringBoot3，需要注意：

• Spring Boot 3 只支持OpenAPI3規(guī)范

• Knife4j提供的starter已經(jīng)引用springdoc-openapi的jar，開發(fā)者需注意避免jar包沖突

• JDK版本必須 >= 17

而且需要引入這個包：

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.0.0</version></dependency>復(fù)制代碼

訪問文檔地址

然后你就可以直接訪問文檔地址了：http://localhost:${port}/${context-path}/doc.html

至此我們就集成完了，有其他疑問歡迎在評論區(qū)提出來??

作者：penga

鏈接：https://juejin.cn/post/7214015651828006967

、文章來源地址http://www.zghlxwxcb.cn/news/detail-425274.html