Springboot3集成Knife4j的步驟以及使用(最完整版)
一,前言
在使用swagger-bootstrap-ui時我覺得它的樣式和藍色主色調(diào)不符合我的審美,所以我覺得使用一個更強的工具 Knife4j。Knife4j是一個用于SpringBoot和SpringCloud的增強Swagger的工具,提供黑色主題和更多配置選項。Knife4j在更名之前,原來的名稱是叫swagger-bootstrap-ui,這是兩種不一樣風(fēng)格的ui顯示,將原來的藍色變成炫酷的黑色模式。
二,Knife4j和swagger-bootstrap-ui對比
工具 | 狀態(tài) | 風(fēng)格 | 配置 |
Knife4j | 持久更新 | 黑色主題 | 支持配置文件編寫配置項 |
swagger-bootstrap-ui | 停更,2.x后更名為Knife4j | 藍色主題 | 不支持 |
三,Spring Boot和Knife4j版本關(guān)系
Spring Boot版本 | Knife4j Swagger 2規(guī)范 | Knife4j OpenAPI 3規(guī)范 |
---|---|---|
1.5.x ~ 2.0.0 | < Knife4j 2.0.0 | >= Knife4j 4.0.0 |
2.0 ~ 2.2 | Knife4j 2.0.0 ~ 2.0.6 | >= Knife4j 4.0.0 |
2.2.x ~ 2.4.0 | Knife4j 2.0.6 ~ 2.0.9 | >= Knife4j 4.0.0 |
2.4.0 ~ 2.7.x | >= Knife4j 4.0.0 | >= Knife4j 4.0.0 |
>= 3.0 | >= Knife4j 4.0.0 | >= Knife4j 4.0.0 |
詳細了解:https://doc.xiaominfo.com/docs/quick-start/start-knife4j-version
注意:
- Spring Boot 只支持 OpenAPI3 規(guī)范
- Knife4j提供的starter已經(jīng)引用了springdoc-openapi的jar包,使用時需要避免jar包沖突
- Springboot3集成Knife4j時需要 JDK版本 >= 17
四,集成步驟
項目環(huán)境:
JDK:17
SpringBoot:3.0.13
Knife4j:4.5.0
1,引入依賴
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId> <version>4.5.0</version> </dependency>
啟動項目就可以查看界面了
2,在application.yml中添加knife4j相關(guān)配置
# springdoc-openapi項目配置 springdoc: swagger-ui: #自定義swagger前端請求路徑,輸入http:localhost:8080/swagger-ui會自動重定向到swagger頁面 path: /swagger-ui tags-sorter: alpha operations-sorter: alpha api-docs: path: /v3/api-docs #swagger后端請求地址 enabled: true #是否開啟文檔功能 group-configs: #分組配置,可配置多個分組 - group: 'default' #分組名稱 paths-to-match: '/**' #配置需要匹配的路徑 packages-to-scan: com.cms #配置要掃描包的路徑,一般配置到啟動類所在的包名 - group: 'admin-api' paths-to-match: '/**' packages-to-scan: com.cms
添加knife4j的增強配置
# knife4j的增強配置,不需要增強可以不配 knife4j: enable: true #開啟knife4j,無需添加@EnableKnife4j注解 setting: language: zh_cn #中文 swagger-model-name: 實體列表 #默認為:Swagger Models #開啟Swagger的Basic認證功能,默認是false,開啟后訪問文檔頁面時會彈出用戶名和密碼輸入框 basic: enable: true # Basic認證用戶名 username: user # Basic認證密碼 password: 123456
3,定義配置類WebMvcConfig
package com.cms.config; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; /** * web層配置類,實現(xiàn)靜態(tài)資源映射,將knife4j相關(guān)資源放行,保證生成的接口文檔能夠正常進行展示 * @author Hva */ @Configuration public class WebMvcConfig implements WebMvcConfigurer { /** * 設(shè)置靜態(tài)資源映射 */ @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { // 添加靜態(tài)資源映射規(guī)則 registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/"); //配置 knife4j 的靜態(tài)資源請求映射地址 registry.addResourceHandler("/doc.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } }
4,定義Knife4j配置類
package com.cms.config; 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 org.springdoc.core.models.GroupedOpenApi; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; /** * Knife4j整合Swagger3 Api接口文檔配置類 * @author Hva */ @Configuration public class Knife4jConfig { /** * 創(chuàng)建了一個api接口的分組 * 除了配置文件方式創(chuàng)建分組,也可以通過注冊bean創(chuàng)建分組 */ @Bean public GroupedOpenApi adminApi() { return GroupedOpenApi.builder() // 分組名稱 .group("app-api") // 接口請求路徑規(guī)則 .pathsToMatch("/**") .build(); } /** * 配置基本信息 */ @Bean public OpenAPI openAPI() { return new OpenAPI() .info(new Info() // 標題 .title("Knife4j整合Swagger3 Api接口文檔") // 描述Api接口文檔的基本信息 .description("Knife4j后端接口服務(wù)...") // 版本 .version("v1.0.0") // 設(shè)置OpenAPI文檔的聯(lián)系信息,姓名,郵箱。 .contact(new Contact().name("Hva").email("Hva@163.com")) // 設(shè)置OpenAPI文檔的許可證信息,包括許可證名稱為"Apache 2.0",許可證URL為"http://springdoc.org"。 .license(new License().name("Apache 2.0").url("http://springdoc.org")) ); } }
重啟項目就可以看到自己配置的信息了
五,基本使用
引入下面測試需要的依賴
<dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> </dependency> <dependency> <groupId>com.baomidou</groupId> <artifactId>mybatis-plus</artifactId> <version>3.5.5</version> </dependency>
1,創(chuàng)建實體類
@Schema(description = ""): 標記實體類屬性
package com.cms.entry; import com.baomidou.mybatisplus.annotation.TableName; import io.swagger.v3.oas.annotations.media.Schema; import lombok.Data; /** * @author Hva */ @Data @TableName("user") @Schema(description = "用戶登錄") public class UserVO { @Schema(description = "用戶名") private String username; @Schema(description = "用戶密碼") private String password; }
2,創(chuàng)建controller
@Tag(name = “ ”): 標記 controler 的類別
@Operation(summary =“ ”): 標記接口操作
package com.cms.controller; import com.cms.entry.UserVO; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.tags.Tag; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RestController; /** * @Author: Hva * @Description: 用戶controller */ @RestController @Tag(name = "用戶controller") public class UserController { /** * 用戶列表 */ @Operation(summary = "登錄接口") @PostMapping("/login") public UserVO list( @RequestBody UserVO userVO ) { return userVO; } }
3,啟動項目
標記的controller 會展示在左側(cè)
使用到的實體會在展示在 實體列表中
4,調(diào)試接口
大功告成,至此,我們對 Knife4j 有了一定的了解和使用,想要了解更多就自己去探索吧?。?!
總結(jié)
到此這篇關(guān)于Springboot3集成Knife4j的步驟以及使用的文章就介紹到這了,更多相關(guān)Springboot3集成Knife4j內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家!
- SpringBoot?Knife4j框架&Knife4j的顯示內(nèi)容的配置方式
- SpringBoot與knife4j的整合使用過程
- springboot讀取bootstrap配置及knife4j版本兼容性問題及解決
- springboot3整合knife4j詳細圖文教程(swagger增強)
- springboot整合knife4j全過程
- knife4j?整合?springboot的過程詳解
- SpringBoot中使用Knife4J的解決方案
- springboot集成swagger3與knife4j的詳細代碼
- Springboot中整合knife4j接口文檔的過程詳解
- knife4j+springboot3.4異常無法正確展示文檔
相關(guān)文章
在Spring Boot中如何使用數(shù)據(jù)緩存
本篇文章主要介紹了在Spring Boot中如何使用數(shù)據(jù)緩存,具有一定的參考價值,有興趣的可以了解一下。2017-04-04Curator實現(xiàn)zookeeper的節(jié)點監(jiān)聽詳解
這篇文章主要介紹了Curator實現(xiàn)zookeeper的節(jié)點監(jiān)聽詳解,Curtor框架中一共有三個實現(xiàn)監(jiān)聽的方式,一種是NodeCache監(jiān)聽指定節(jié)點,一種是pathChildrenCache監(jiān)聽子節(jié)點,一種是TreeCache可以監(jiān)控所有節(jié)點 相當于以上兩種的合集,需要的朋友可以參考下2023-12-12SpringBoot將所有依賴(包括本地jar包)打包到項目
這篇文章主要介紹了SpringBoot將所有依賴(包括本地jar包)打包到項目,本文通過示例代碼給大家介紹的非常詳細,對大家的學(xué)習(xí)或工作具有一定的參考借鑒價值,需要的朋友可以參考下2023-06-06Java內(nèi)存各部分OOM出現(xiàn)原因及解決方法(必看)
下面小編就為大家?guī)硪黄狫ava內(nèi)存各部分OOM出現(xiàn)原因及解決方法(必看)。小編覺得挺不錯的,現(xiàn)在就分享給大家,也給大家做個參考。一起跟隨小編過來看看吧2017-04-04Springmvc調(diào)用存儲過程,并返回存儲過程返還的數(shù)據(jù)方式
這篇文章主要介紹了Springmvc調(diào)用存儲過程,并返回存儲過程返還的數(shù)據(jù)方式,具有很好的參考價值,希望對大家有所幫助。如有錯誤或未考慮完全的地方,望不吝賜教2021-11-11Java如何實現(xiàn)Unicode和中文相互轉(zhuǎn)換
這篇文章主要介紹了Java如何實現(xiàn)Unicode和中文相互轉(zhuǎn)換問題,具有很好的參考價值,希望對大家有所幫助,如有錯誤或未考慮完全的地方,望不吝賜教2024-01-01