Spring?Boot項目集成Knife4j接口文檔的實例代碼
Knife4j
就相當(dāng)于是swagger
的升級版,對于我來說,它比swagger
要好用得多
1、在pom.xml引入依賴包
<!-- Swagger配置依賴knife4j --> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>2.0.9</version> </dependency>
2、創(chuàng)建Knife4j配置文件
package com.yuyun.config; import io.swagger.annotations.ApiOperation; import io.swagger.models.auth.In; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.ApiKey; import springfox.documentation.service.Contact; import springfox.documentation.service.SecurityScheme; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc; import java.util.ArrayList; import java.util.List; /** * @author hyh */ @Configuration @EnableSwagger2WebMvc public class Knife4jConfiguration { @Bean(value = "defaultApi2") public Docket defaultApi2() { Docket docket = new Docket(DocumentationType.SWAGGER_2) // 是否啟用Swagger .enable(true) //分組名稱 .groupName("1.0版本") // 用來創(chuàng)建該API的基本信息,展示在文檔的頁面中(自定義展示的信息) .apiInfo(apiInfo()) // 設(shè)置哪些接口暴露給Swagger展示 .select() // 掃描所有有注解的api,用這種方式更靈活 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //指定Controller掃描包路徑 // .apis(RequestHandlerSelectors.basePackage("com.yuyun.controller")) // 掃描所有 // .apis(RequestHandlerSelectors.any()) .build(); return docket; } private ApiInfo apiInfo() { String name = "雨云"; String url = "https://www.xxx.com/"; String email = "1873591403@qq.com"; Contact contact = new Contact(name, url, email); return new ApiInfoBuilder() .title("API接口文檔") .description("API接口文檔描述") .termsOfServiceUrl("https://www.xx.com/") .contact(contact) .version("1.0.1") .build(); } }
注意:如果出現(xiàn)錯誤Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
是因為SpringBoot版本高了,將版本降下去或者在application.yml
添加如下內(nèi)容即可解決該錯誤
spring: mvc: pathmatch: matching-strategy: ant_path_matcher
項目運行后,訪問ip
+端口號
+/doc.html
,比如http://localhost:8110/doc.html。效果如圖
3、使用Knife4j注解
(1)在實體類中使用
@ApiModel
放在在響應(yīng)實體類上,用于描述該類
@ApiModelProperty
描述該響應(yīng)類的屬性
/** * 企業(yè)信息表 * * @author * @since 1.0.0 2021-12-17 */ @Data @ApiModel(value = "企業(yè)信息表") @TableName("company") public class CompanyDTO implements Serializable { private static final long serialVersionUID = 1L; /** * 主鍵 */ @ApiModelProperty(value = "主鍵") private Long id; /** * 企業(yè)名稱 */ @ApiModelProperty(value = "企業(yè)名稱") private String companyName; /** * 簡介 */ @ApiModelProperty(value = "簡介") private String description; }
(2)在Controller層使用
@RestController @RequestMapping("company") @Api(tags = "企業(yè)信息表") public class CompanyController { @Autowired private CompanyService companyService; @GetMapping("getList") @ApiOperation("根據(jù)條件獲取數(shù)據(jù)") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "id", paramType = "query", required = true, dataType = "String"), @ApiImplicitParam(name = "name", value = "名稱", paramType = "query", required = true, dataType = "String") }) public Result<List<CompanyDTO>> getList(@ApiParam(name = "address", value = "地址", required = true) String address) { List<CompanyDTO> companyList = companyService.list(); return new Result<List<CompanyDTO>>().success(companyList); } }
還有其他一些注解,用到再了解
4、全局參數(shù)
在實際項目中訪問接口都添加了權(quán)限,每次訪問都要帶一個請求頭參數(shù)token。全局參數(shù)就是為了方便傳一個固定的參數(shù)。當(dāng)添加全局參數(shù)后,所有的接口都會帶上該參數(shù)。
第一種
在配置文件中加入
private List<SecurityScheme> securitySchemes() { List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>(); apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue())); return apiKeyList; }
在defaultApi2()
方法內(nèi)引用
.securitySchemes(securitySchemes())
最后配置文件中的內(nèi)容:
@Configuration @EnableSwagger2WebMvc public class Knife4jConfiguration { @Bean(value = "defaultApi2") public Docket defaultApi2() { Docket docket = new Docket(DocumentationType.SWAGGER_2) // 是否啟用Swagger .enable(true) //分組名稱 .groupName("1.0版本") // 用來創(chuàng)建該API的基本信息,展示在文檔的頁面中(自定義展示的信息) .apiInfo(apiInfo()) // 設(shè)置哪些接口暴露給Swagger展示 .select() // 掃描所有有注解的api,用這種方式更靈活 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //指定Controller掃描包路徑 // .apis(RequestHandlerSelectors.basePackage("com.yuyun.controller")) // 掃描所有 // .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build() /* 設(shè)置安全模式,swagger可以設(shè)置訪問token */ .securitySchemes(securitySchemes()) .securityContexts(securityContexts()) .pathMapping("/"); return docket; } private ApiInfo apiInfo() { String name = "雨云"; String url = "https://www.xxx.com/"; String email = "1873591403@qq.com"; Contact contact = new Contact(name, url, email); return new ApiInfoBuilder() .title("API接口文檔") .description("API接口文檔描述") .termsOfServiceUrl("https://www.xx.com/") .contact(contact) .version("1.0.1") .build(); } /** * 安全模式,這里指定token通過Authorization頭請求頭傳遞 */ private List<SecurityScheme> securitySchemes() { List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>(); apiKeyList.add(new ApiKey("Authorization", "Authorization", "header")); return apiKeyList; } /** * 安全上下文 */ private List<SecurityContext> securityContexts() { List<SecurityContext> securityContexts = new ArrayList<>(); securityContexts.add( SecurityContext.builder() .securityReferences(defaultAuth()) .build()); return securityContexts; } /** * 默認(rèn)的安全上引用 */ private List<SecurityReference> defaultAuth() { AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything"); AuthorizationScope[] authorizationScopes = new AuthorizationScope[1]; authorizationScopes[0] = authorizationScope; List<SecurityReference> securityReferences = new ArrayList<>(); securityReferences.add(new SecurityReference("Authorization", authorizationScopes)); return securityReferences; } }
效果:菜單上多了一個Authorize
,在參數(shù)值中添加上信息
刷新一下,再打開接口就會發(fā)現(xiàn)多了個請求頭部
第二種
直接在菜單文檔管理
→全局參數(shù)設(shè)置
,然后添加參數(shù):
再打開接口就會發(fā)現(xiàn)請求頭參數(shù)加上了
源碼地址:https://gitee.com/hyh17808770899/spring-boot/tree/master/springboot-03
到此這篇關(guān)于Spring Boot項目集成Knife4j接口文檔的文章就介紹到這了,更多相關(guān)Spring Boot集成Knife4j接口文檔內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家!
相關(guān)文章
Java Swing JButton按鈕的實現(xiàn)示例
這篇文章主要介紹了Java Swing JButton按鈕的實現(xiàn)示例,文中通過示例代碼介紹的非常詳細,對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值,需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2019-12-12springboot整合mybatis實現(xiàn)數(shù)據(jù)庫的更新批處理方式
這篇文章主要介紹了springboot整合mybatis實現(xiàn)數(shù)據(jù)庫的更新批處理方式,具有很好的參考價值,希望對大家有所幫助。如有錯誤或未考慮完全的地方,望不吝賜教2023-03-03Mybatis使用JSONObject接收數(shù)據(jù)庫查詢的方法
這篇文章主要介紹了Mybatis使用JSONObject接收數(shù)據(jù)庫查詢,本文給大家介紹的非常詳細,對大家的學(xué)習(xí)或工作具有一定的參考借鑒價值,需要的朋友可以參考下2021-12-12