这把小刀怎么用——详解Knife4j框架

目录

介绍

使用步骤

        1.在maven中添加依赖

        2.添加其配置类，可以放在项目其他框架的配置类包中

        3.application.properties中添加配置

---

介绍

        Knife4j是为Java MVC框架集成Swagger生成在线Api文档的增强解决方案,其前身是swagger-bootstrap-ui，此框架还有调试功能，可以向服务器端发送请求，并获取响应结果。简单的说就是帮我们自动生成了文档注解，而且可以直接在图形化界面中向服务器发起请求，便于调试。
 

使用步骤

        1.在maven中添加依赖
 

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

        2.添加其配置类，可以放在项目其他框架的配置类包中
 

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 lee
 * @version 0.0.1
 */
@Slf4j
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    /**
     * 【重要】指定Controller包路径
     */
    private String basePackage = "com.lee.test.product.controller";
    /**
     * 分组名称
     */
    private String groupName = "product";
    /**
     * 主机名
     */
    private String host = "http://lee.com";
    /**
     * 标题
     */
    private String title = "演示在线API文档--商品管理";
    /**
     * 简介
     */
    private String description = "演示在线API文档--商品管理";
    /**
     * 服务条款URL
     */
    private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";
    /**
     * 联系人
     */
    private String contactName = "lee-coding";
    /**
     * 联系网址
     */
    private String contactUrl = "lee-coding.blog.csdn.net";
    /**
     * 联系邮箱
     */
    private String contactEmail = "lee@xx.mail";
    /**
     * 版本号
     */
    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();
    }

}

以上内容可以选择复制粘贴。

        3.application.properties中添加配置
 

#..
knife4j.enable=true

注意：

当前项目的Spring Boot版本是2.5.9，必须是2.6以下的版本（2.6不可用）如果要使用更高版本的Spring Boot，必须使用更高版本的Knife4j

在配置类中的basePackage必须是控制器类所在的包

完成后，启动项目，通过 /doc.html 即可访问在线API文档。界面效果：

 这时我们看到的就是knife4j提供给我们的界面，左边这一列会列出所有的controller，以及里面的所有处理请求的方法，现在我们加入一个ProductController 控制器类：
 

@Slf4j
@RestController
@RequestMapping("/products")
public class ProductController {
    public ProductController(){
        log.debug("创建商品控制器");
    }
    @RequestMapping("/add-new")
    public String addNew(){
        return "添加成功";
    }
}

然后再次运行启动类，刷新页面看到如下效果

 

 我们可以看到在接口统计信息中已经多出了7个接口相关信息，并在左侧图中多出了我们所创建的ProductController。虽然我们只有一个处理请求的方法，但由于我们没有定义具体的请求方式，所以框架帮我们列出了所有的请求方式。因为是添加产品业务，所以我们改为Post请求，另外框架还为我们提供了很丰富的注解，例如：@Api，可以在控制器类上面添加并设置tags属性    @ApiOperation，可以在控制器类中处理请求的对应方法上面添加，并配置value属性，代码如下：

这时我们再看前端展示页面： 
 

 类名和方法名都改为了中文，而且请求方式也发生了改变。我们点击处理添加请求的方法：

可以看到里面有详细的请求参数，相应类型等等，由于我们的方法中未定义任何参数和业务逻辑，所以显示为空，现在我们为addNew这个方法传入一个ProductAddNewDTO数据传输对象，并在这个类中定义几个变量。如下代码：
 

@Slf4j
@Api(tags = "商品管理模块")
@RestController
@RequestMapping("/products")
public class ProductController {

    public ProductController(){
        log.debug("创建商品控制器");
    }
    @ApiOperation(value = "添加产品")
    @PostMapping("/add-new")
    public String addNew(ProductAddNewDTO productAddNewDTO){
        return "添加成功";
    }
}

 

@Data
@Accessors(chain = true)
public class ProductAddNewDTO {
    private String name;
    private String description;
    private Integer id;
}

添加成功后，我们再去前端页面就会看到参数列表 ，以及对应的信息和属性：

 点击调试，还可以直接向服务器发送请求，获取响应信息：

以上就是简单的使用介绍。当然其中还有很多实用的注解，以及功能特效。这里就不一一赘述，大家感兴趣可以自己研究一下