Knife4j框架介绍

一，什么是Knife4j框架

Knife4j是一款基于Swagger 2的在线API文档框架，是日常开发中很常用的框架，基于此框架，后端可以和前端开发人员进行高效沟通。

二，怎样使用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";
    /**
     * 联系人
     */
    private String contactName = "Java教学研发部";
    /**
     * 联系网址
     */
    private String contactUrl = "http://java.tedu.cn";
    /**
     * 联系邮箱
     */
    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属性，可以指定模块名称，并且，在指定名称时，建议在名称前添加数字作为序号，Knife4j会根据这些数字将各模块升序排列，例如：

@Api(tags = "01. 管理员管理模块")

@ApiOpearation：添加在控制器类中处理请求的方法上，通过此注解的value属性，可以指定业务/请求资源的名称，例如：

@ApiOperation("添加管理员")

@ApiOperationSupport：添加在控制器类中处理请求的方法上，通过此注解的order属性（int），可以指定排序序号，Knife4j会根据这些数字将各业务/请求资源升序排列，例如：

@ApiOperationSupport(order = 100)

如果处理请求时，参数是封装的POJO类型，需要对各请求参数进行说明时，应该在此POJO类型的各属性上使用***@ApiModelProperty注解进行配置，通过此注解的value***属性配置请求参数的名称，通过requeired属性配置是否必须提交此请求参数（并不具备检查功能），例如：

@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还可以用于配置响应时的各数据！

对于处理请求的方法的参数列表中那些未封装的参数（例如String、Long），需要在处理请求的方法上使用***@ApiImplicitParam注解来配置参数的说明，并且，必须配置name属性，此属性的值就是方法的参数名称，使得此注解的配置与参数对应上，然后，再通过value属性对参数进行说明，还要注意，此属性的required属性表示是否必须提交此参数，默认为false***，即使是用于配置路径上的占位符参数，一旦使用此注解，required默认也会是false，则需要显式的配置为true，另外，还可以通过dataType配置参数的数据类型，如果未配置此属性，在API文档中默认显示为string，可以按需修改为int、long等。例如：

@ApiImplicitParam(name = "id", value = "相册id", required = true, dataType = "long")
@PostMapping("/{id:[0-9]+}/delete")
public JsonResult delete(@PathVariable Long id) {
    // 暂不关心方法内部的代码
}

最后效果如下：