一，什么是Knife4j框架

Knife4j是一款基于Swagger 2的在線API文檔框架，是日常開發(fā)中很常用的框架，基于此框架，后端可以和前端開發(fā)人員進行高效溝通。

二，怎樣使用Knife4j框架

使用Knife4j框架只需要以下三步：
1：添加Knife4j的依賴（當前建議使用的Knife4j版本，只適用于Spring Boot 2.6以下版本，不含Spring Boot 2.6）

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

2：在主配置文件（application.properties）中開啟Knife4j的增強模式

knife4j.enable=true

3：添加Knife4j的配置類，進行必要的配置（必須指定控制器的包）

package cn.tedu.csmall.product.config;

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@fwh.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";
    /**
     * 標題
     */
    private String title = "xx商城在線API文檔--管理員管理";
    /**
     * 簡介
     */
    private String description = "xx商城在線API文檔--管理員管理";
    /**
     * 服務條款URL
     */
    private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";
    /**
     * 聯(lián)系人
     */
    private String contactName = "Java教學研發(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("加載配置類：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();
    }

}

完成后，啟動項目，通過 http://localhost:端口號/doc.html 即可訪問在線API文檔！

三，關于Knife4j框架的顯示注解

***@Api ***：添加在控制器類上，通過此注解的tags屬性，可以指定模塊名稱，并且，在指定名稱時，建議在名稱前添加數(shù)字作為序號，Knife4j會根據(jù)這些數(shù)字將各模塊升序排列，例如：

@Api(tags = "01. 管理員管理模塊")

@ApiOpearation：添加在控制器類中處理請求的方法上，通過此注解的value屬性，可以指定業(yè)務/請求資源的名稱，例如：

@ApiOperation("添加管理員")

@ApiOperationSupport：添加在控制器類中處理請求的方法上，通過此注解的order屬性（int），可以指定排序序號，Knife4j會根據(jù)這些數(shù)字將各業(yè)務/請求資源升序排列，例如：

@ApiOperationSupport(order = 100)

如果處理請求時，參數(shù)是封裝的POJO類型，需要對各請求參數(shù)進行說明時，應該在此POJO類型的各屬性上使用***@ApiModelProperty注解進行配置，通過此注解的value***屬性配置請求參數(shù)的名稱，通過requeired屬性配置是否必須提交此請求參數(shù)（并不具備檢查功能），例如：

@Data
public class AlbumAddNewDTO implements Serializable {

    /**
     * 相冊名稱
     */
    @ApiModelProperty(value = "相冊名稱", example = "小米10的相冊", required = true)
    private String name;

    /**
     * 相冊簡介
     */
    @ApiModelProperty(value = "相冊簡介", example = "小米10的相冊的簡介", required = true)
    private String description;

    /**
     * 排序序號
     */
    @ApiModelProperty(value = "排序序號", example = "98", required = true)
    private Integer sort;

}

需要注意，@ApiModelProperty還可以用于配置響應時的各數(shù)據(jù)！

對于處理請求的方法的參數(shù)列表中那些未封裝的參數(shù)（例如String、Long），需要在處理請求的方法上使用***@ApiImplicitParam注解來配置參數(shù)的說明，并且，必須配置name屬性，此屬性的值就是方法的參數(shù)名稱，使得此注解的配置與參數(shù)對應上，然后，再通過value屬性對參數(shù)進行說明，還要注意，此屬性的required屬性表示是否必須提交此參數(shù)，默認為false***，即使是用于配置路徑上的占位符參數(shù)，一旦使用此注解，required默認也會是false，則需要顯式的配置為true，另外，還可以通過dataType配置參數(shù)的數(shù)據(jù)類型，如果未配置此屬性，在API文檔中默認顯示為string，可以按需修改為int、long等。例如：

@ApiImplicitParam(name = "id", value = "相冊id", required = true, dataType = "long")
@PostMapping("/{id:[0-9]+}/delete")
public JsonResult delete(@PathVariable Long id) {
    // 暫不關心方法內(nèi)部的代碼
}

最后效果如下：
文章來源地址http://www.zghlxwxcb.cn/news/detail-648374.html

到了這里，關于Knife4j框架介紹的文章就介紹完了。如果您還想了解更多內(nèi)容，請在右上角搜索TOY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關文章，希望大家以后多多支持TOY模板網(wǎng)！