HiDocs
Search K

Appearance

原文网址： Knife4j--使用/教程/实例/配置_IT 利刃出鞘的博客-CSDN 博客

说明

本文用示例介绍 knife4j 的用法。（SpringBoot 整合 knife4j）

Knife4j 是一个很好用的接口文档工具。之前用过 Swagger，觉得页面不太好，浏览技术网站时，偶然发现 swagger-bootstrap-ui，它能将接口进行归类。

早期，swagger-boostrap-ui 是 1.x 版本，如今 swagger-bootsrap-ui 到 2.x，同时也更改名字 Knife4j，适用于单体和微服务项目。

Knife4j 跟 Swagger 用法基本一样，swagger 用法见： Swagger--使用/教程/实例/配置_IT 利刃出鞘的博客-CSDN 博客

官网

首页： knife4j

文档： knife4j

gitee 地址： https://gitee.com/xiaoym/knife4j

官网文档： 1.6 快速开始 | knife4j

依赖及配置 ​

依赖 ​

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

本处我使用比较新的版本展示。（目前 2.0.9 是最新的发布版，最稳定。）

版本的区别如下：

Knife4j 配置（非必要） ​

配置方案：使用 openApi3.0

默认引入包就可以直接用了（无需配置）。本处只是示例如果自定义一些东西该怎么写。

java
package com.example.demo.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableOpenApi
// @EnableKnife4j
// @EnableSwagger2
public class Knife4jConfig {
    @Bean
    public Docket docket() {
        Docket docket = new Docket(DocumentationType.OAS_30)
                .apiInfo(new ApiInfoBuilder()
                        .title("我的标题")
                        .description("我的描述")
                        // .termsOfServiceUrl("http://www.xx.com/")
                        .contact(new Contact("knife", "https://knife.blog.csdn.net/", "xx@qq.com"))
                        .version("1.0")
                        .build())
                // 分组名称
                .groupName("all")
                .select()
                // 这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();

        return docket;
    }
}

其他配置方案：使用 swagger2

java
package com.example.demo.config;

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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Knife4jConfig {
    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("我的标题")
                        .description("我的描述")
                        // .termsOfServiceUrl("http://www.xx.com/")
                        .contact(new Contact("IT利刃出鞘", "https://knife.blog.csdn.net", "xx@qq.com"))
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("all")
                .select()
                //指定Controller扫描路径。可以不具体到controller，它会扫描指定路径下的所有
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

代码 ​

Controller ​

java
package com.example.demo.business.user.controller;

import com.example.demo.business.user.request.UserAddRequest;
import com.example.demo.business.user.request.UserEditRequest;
import com.example.demo.business.user.request.UserQueryRequest;
import com.example.demo.business.user.vo.UserVO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.BeanUtils;
import org.springframework.web.bind.annotation.*;

import javax.validation.Valid;
import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.List;

@Api(tags = "用户")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation("添加")
    @PostMapping("/add")
    public UserVO add(@RequestBody @Valid UserAddRequest userAddRequest) {
        // 将数据写到数据库
        UserVO userVO = new UserVO();
        BeanUtils.copyProperties(userAddRequest, userVO);
        userVO.setId(1L);
        userVO.setCreateTime(LocalDateTime.now());
        userVO.setUpdateTime(LocalDateTime.now());
        return userVO;
    }

    @ApiOperation("修改")
    @PostMapping("/edit")
    public UserVO edit(@RequestBody @Valid UserEditRequest userEditRequest) {
        // 修改数据库的数据
        UserVO userVO = new UserVO();
        BeanUtils.copyProperties(userEditRequest, userVO);
        userVO.setUpdateTime(LocalDateTime.now());
        return userVO;
    }

    @ApiOperation("查找")
    @GetMapping("/find")
    public List<UserVO> find(UserQueryRequest userQueryRequest) {
        return new ArrayList<>();
    }

    @ApiOperation("删除")
    @PostMapping("/delete")
    public void delete(Long id) {
        // 将数据库数据删除
    }
}

Entity ​

说明

本处我将增删改查都单独写一个实体类。

当然，也可以将增删改的参数都写到一个实体里边，通过@Null，@NotNull 以及它们的 groups 属性来指定属于哪个分组。这样写在运行时不会有问题，但在 Knife4j 页面显示时会不正常，原因是：Swagger 没有很好地处理好这种情况。

添加

java
package com.example.demo.business.user.request;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import javax.validation.constraints.NotBlank;

@Data
@ApiModel("添加用户")
public class UserAddRequest {
    @ApiModelProperty(value = "用户名", required = true)
    @NotBlank(message = "用户名不能为空")
    private String userName;

    @ApiModelProperty("昵称")
    private String nickName;

    @ApiModelProperty("邮箱")
    private String email;
}

修改

java
package com.example.demo.business.user.request;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;

@Data
@ApiModel("修改用户")
public class UserEditRequest {
    @ApiModelProperty(value = "用户ID", required = true)
    @NotNull(message = "用户ID不能为空")
    private Long id;

    @ApiModelProperty(value = "用户名", required = true)
    @NotBlank(message = "用户名不能为空")
    private String userName;

    @ApiModelProperty("昵称")
    private String nickName;

    @ApiModelProperty("邮箱")
    private String email;
}

查询

java
package com.example.demo.business.user.request;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import org.springframework.format.annotation.DateTimeFormat;

import java.time.LocalDateTime;

@Data
@ApiModel(value = "用户实体", description = "用户description")
public class UserQueryRequest {

    @ApiModelProperty("用户id")
    private Long id;

    @ApiModelProperty("用户名")
    private String userName;

    @ApiModelProperty("昵称")
    private String nickName;

    @ApiModelProperty("邮箱")
    private String email;

    @ApiModelProperty("创建时间")
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime createTime;

    @ApiModelProperty("修改时间")
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime updateTime;
}

VO ​

java
package com.example.demo.business.user.vo;

import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.time.LocalDateTime;

@Data
@ApiModel(value = "用户实体", description = "用户description")
public class UserVO {

    @ApiModelProperty("用户id")
    private Long id;

    @ApiModelProperty("用户名")
    private String userName;

    @ApiModelProperty("昵称")
    private String nickName;

    @ApiModelProperty("邮箱")
    private String email;

    @ApiModelProperty(value = "创建时间")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime createTime;

    @ApiModelProperty(value = "修改时间")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime updateTime;

    @ApiModelProperty("删除标记。0：未删除 其他：已删除")
    private Long deletedFlag;
}

测试 ​

knife4j 跟 Tomcat 共用一个端口，默认 Tomcat 是 8080。访问地址：

localhost:8080/doc.html

img

分组 Url

“分组 Url”是文档地址，其他软件（比如 apifox）可以将它作为导入文档的 url。

此网址可以直接访问： localhost:8080/v3/api-docs?group=all

img

文档 ​

本处展示添加用户接口的文档：

img

img

自测 ​

本处展示添加用户的自测方法

img

测试结果

img

全局响应的处理

见： Knife4j--解决整合@ControllerAdvice 时访问失败的问题_IT 利刃出鞘的博客-CSDN 博客

清缓存

见： Knife4j--清除缓存的方法_IT 利刃出鞘的博客-CSDN 博客

上传文件

见： Knife4j--解决不显示文件上传的问题_IT 利刃出鞘的博客-CSDN 博客