SpringBoot Knife4j在線API文檔框架基本使用
1.Knife4j在線API文檔基本使用
Knife4j是一款基于Swagger 2的在線API文檔框架。
使用Knife4j的基礎(chǔ)步驟:
- 添加依賴
- 在
application.properties
/application.yml
中添加配置 - 在項目中添加配置類
關(guān)于依賴項:
<!-- Knife4j Spring Boot:在線API --> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <version>2.0.9</version> </dependency>
注意:以上依賴項的版本是2.0.9
,適用于Spring Boot 2.6以下(不含2.6)版本。
關(guān)于配置文件中的配置,主要是開啟此框架的增強模式(Knife4j定義的概念),需要添加:
knife4j.enable=true
關(guān)于配置類:
import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver; import lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.annotation.Autowired; 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.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc; /** * Knife4j配置類 * * @author java@tedu.cn * @version 0.0.1 */ @Slf4j @Configuration @EnableSwagger2WebMvc public class Knife4jConfiguration { /** * 【重要】指定Controller包路徑 */ private String basePackage = "cn.tedu.csmall.product.controller"; /** * 分組名稱 */ private String groupName = "product"; /** * 主機名 */ private String host = "http://java.tedu.cn"; /** * 標(biāo)題 */ private String title = "商城在線API文檔--商品管理"; /** * 簡介 */ private String description = "商城在線API文檔--商品管理"; /** * 服務(wù)條款URL */ private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0"; /** * 聯(lián)系人 */ private String contactName = "Java教學(xué)研發(fā)部"; /** * 聯(lián)系網(wǎng)址 */ private String contactUrl = "http://java.tedu.cn"; /** * 聯(lián)系郵箱 */ private String contactEmail = "java@tedu.cn"; /** * 版本號 */ private String version = "1.0.0"; @Autowired private OpenApiExtensionResolver openApiExtensionResolver; public Knife4jConfiguration() { log.debug("創(chuàng)建配置類對象:Knife4jConfiguration"); } @Bean public Docket docket() { String groupName = "1.0.0"; Docket docket = new Docket(DocumentationType.SWAGGER_2) .host(host) .apiInfo(apiInfo()) .groupName(groupName) .select() .apis(RequestHandlerSelectors.basePackage(basePackage)) .paths(PathSelectors.any()) .build() .extensions(openApiExtensionResolver.buildExtensions(groupName)); return docket; } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title(title) .description(description) .termsOfServiceUrl(termsOfServiceUrl) .contact(new Contact(contactName, contactUrl, contactEmail)) .version(version) .build(); } }
注意:務(wù)必檢查以上配置類中的basePackage
屬性的值,必須是當(dāng)前項目中控制器類所在的包!
在項目中已經(jīng)完成以上步驟后,啟動項目,打開瀏覽器,通過http://localhost:8080/doc.html即可訪問在線API文檔。
2.配置API文檔信息
@Api
:添加在控制器類上
- 此注解的
tags
屬性,可配置模塊名稱,可以在模塊名稱中使用編號,例如:01. 品牌管理模塊,最終將按照編號升序排列
@ApiOperation
:添加在控制器類中處理請求的方法上
- 此注解的
value
屬性,可配置業(yè)務(wù)名稱
@ApiOperationSupport
:添加在控制器類中處理請求的方法上
- 此注解的
order
屬性(int
類型),可配置業(yè)務(wù)的排序序號,最終將升序排列
@ApiModelProperty
:添加在POJO類型的屬性上
- 此注解的
value
屬性,可配置參數(shù)名稱(說明) - 此注解的
required
屬性,可配置是否必須提交此參數(shù) - 此注解的
example
屬性,可配置此請求參數(shù)的示例值
@ApiImplicitParam
:添加在控制器類中處理請求的方法上,用于對未封裝的請求參數(shù)添加說明(例如Long id
參數(shù))
- 必須配置此注解的
name
屬性,取值為方法的參數(shù)名稱,表示當(dāng)前注解對哪個參數(shù)進(jìn)行說明 - 此注解的
value
屬性,可配置參數(shù)名稱(說明) - 此注解的
required
屬性,可配置是否必須提交此參數(shù) - 此注解的
dataType
屬性,可配置參數(shù)的數(shù)據(jù)類型(例如取值為"long"
) - 此注解的
example
屬性,可配置此請求參數(shù)的示例值
@ApiImplicitParams
:添加在控制器類中處理請求的方法上,此注解的value
屬性是@ApiImplicitParam
注解的數(shù)組類型,當(dāng)需要使用@ApiImplicitParam
對多個未封裝參數(shù)進(jìn)行說明時,需要將多個@ApiImplicitParam
注解的配置作為當(dāng)前注解的參數(shù)
@ApiOperation("刪除類別") @ApiOperationSupport(order = 200) @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "類別ID", required = true, dataType = "long"), @ApiImplicitParam(name = "userId", value = "用戶ID", required = true, dataType = "long") }) @PostMapping("/delete") public void delete(Long userId, Long id) {}
到此這篇關(guān)于SpringBoot Knife4j在線API文檔框架基本使用的文章就介紹到這了,更多相關(guān)SpringBoot Knife4j 內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家!
相關(guān)文章
利用Java實現(xiàn)動態(tài)加載數(shù)據(jù)庫
這篇文章主要為大家詳細(xì)介紹了一個java小案例,即動態(tài)加載數(shù)據(jù)庫信息,文中的示例代碼簡潔易懂,具有一定的學(xué)習(xí)價值,感興趣的小伙伴可以了解一下2023-10-10Java下利用Jackson進(jìn)行JSON解析和序列化示例
本篇文章主要介紹了Java下利用Jackson進(jìn)行JSON解析和序列化示例,具有一定的參考價值,感興趣的小伙伴們可以參考一下。2017-02-02關(guān)于SpringMVC中控制器如何處理文件上傳的問題
這篇文章主要介紹了關(guān)于SpringMVC中控制器如何處理文件上傳的問題,在 Web 應(yīng)用程序中,文件上傳是一個常見的需求,例如用戶上傳頭像、上傳文檔等,本文將介紹 Spring MVC 中的控制器如何處理文件上傳,并提供示例代碼,需要的朋友可以參考下2023-07-07Mybatis-plus使用注解 @TableField(exist = false)
這篇文章主要介紹了Mybatis-plus使用注解 @TableField(exist = false),文中通過示例代碼介紹的非常詳細(xì),對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值,需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2021-03-03