SpringBoot整合Knife4j框架

相关
简化代码的Lombok(跳转)

---

一、Knife4j

Knife4j是国人开发的一个基于Swagger2的在线文档框架, 可以说是Swagger的升级版的API文档框架, 它可以扫描控制器所在的包, 并解析每一个控制器及其内部的处理请求的方法, 生成在线API文档, 为前后端的开发人员的沟通提供便利

二、环境准备

1.引入依赖

创建SpringBoot项目, 勾选Spring web框架 , 并在pom.xml中添加依赖：

<dependency>
    <groupId>com.github.xiaoymingroupId>
    <artifactId>knife4j-spring-boot-starterartifactId>
    <version>2.0.9version>
dependency>

<dependency>
	<groupId>org.projectlombokgroupId>
	<artifactId>lombokartifactId>
	<optional>trueoptional>
dependency>

2.添加配置

引入依赖后, 在application.properties中添加配置：

#启用knife4j增强模式
knife4j.enable=true
#生产模式屏蔽, true将禁止访问API在线文档, false可以看到文档, 密码失效
knife4j.production=false
#Basic认证功能，即是否需要通过用户名、密码验证后才可以访问在线API文档
knife4j.basic.enable=true
#如果开启Basic认证却未配置用户名与密码，默认是：admin/123321, 即使输入对了, 也会一直循环
knife4j.basic.username=root
knife4j.basic.password=root
#为了节省流量, 返回数据时, 配置不返回属性值为null的数据
spring.jackson.default-property-inclusion=non_null

3.设置配置类

以上两步完成后, 在项目配置包下创建Knife4jConfiguration.class类

package cn.qingtian.knife4j.config;

import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
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（Swagger2）的配置
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    /**
     * 【重要】指定Controller包路径
     */
    private String basePackage = "cn.qingtian.knife4j.controller";
    /**
     * 分组名称
     */
    private String groupName = "base-knife4j";
    /**
     * 主机名
     */
    private String host = "http://java.qingtian.cn";
    /**
     * 标题
     */
    private String title = "API在线文档工具";
    /**
     * 简介
     */
    private String description = "Knife4j演示";
    /**
     * 服务条款URL
     */
    private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";
    /**
     * 联系人
     */
    private String contactName = "项目研发部";
    /**
     * 联系网址
     */
    private String contactUrl = "http://java.qingtian.cn";
    /**
     * 联系邮箱
     */
    private String contactEmail = "[email protected]";
    /**
     * 版本号
     */
    private String version = "1.0.0";

    @Autowired
    private OpenApiExtensionResolver openApiExtensionResolver;

    @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();
    }

}

4.运行访问

前三步完成后, 启动此项目, 在浏览器上访问http://localhost:8080/doc.html, 输入账号密码= root/root

三、基本用法

1.控制器

• Api : 添加在控制类上, 通过tags属性, 可以指定此控制器的名称, 还可以在tags上添加序号, 控制各控制器之间的排序, 如"1. 管理员模块" "2. 评论模块" Knife4j框架会自动进行排序
• @ApiOperation : 添加在控制器类中的处理方法上, 用于配置方法在API文档中的名称, 如@ApiOperation("增加管理员")
• @ApiOperationSupport : 添加在控制器类的处理方法上, 通过属性order, 可配置在本控制器上此方法的显示排序, 建议增(order=10), 删(order=20), 改(order=30), 查(order=40)
• @ApiImplicitParam : 添加在控制器类的处理方法上, 可以配置此方法参数在API文档中的显示, 属性name方法名 value方法描述 required是否必须 dataType参数类型 example参数示例
• @ApiImplicitParams : 添加在控制器类的处理方法上, 与@ApiImplicitParam配合使用, 用于有多个参数的方法, 如@ApiImplicitParams(@ApiImplParam(参数1配置), @ApiImplParam(参数2配置))

2.封装类

• @ApiModel : 添加在封装类上, 用于配置封装类在API文档中的名称, 如@ApiModel("用户数据")
• @ApiModelProperty : 添加在封装类中的属性上, 用于配置封装类在API文档中的显示, 常用属性value属性名称 required是否必须 exampl参数实例 dataType参数类型

在自定义的封装类中, 必须有GET和SET方法, 不然会出现 406-文件不可被接收错误

四、效果演示

在cn.qingtian.knife4j下创建包pojo, 在pojo下创建dto和vo并创建以下类

package cn.qingtian.knife4j.pojo.dto;

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

import java.io.Serializable;

@Data
@ApiModel("用户DTO")
public class UserDTO implements Serializable {
    @ApiModelProperty(value = "用户账号",example = "java1234567", required = true)
    private String username;
    @ApiModelProperty(value = "用户密码",example = "12345678", required = true)
    private String password;
}

package cn.qingtian.knife4j.pojo.vo;

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

import java.io.Serializable;

@Data
@ApiModel("用户VO")
public class UserVO implements Serializable {
    @ApiModelProperty(name = "username",value = "用户账号",example = "java1234567")
    private String username;
    @ApiModelProperty(name = "password",value = "用户密码",example = "12345678")
    private String password;
}

在cn.qingtian.knife4j下创建包response, 并创建以下类

package cn.qingtian.knife4j.response;

/**
 * 枚举类, 定义本项目的业务返回码
 */
public enum ResponseCode {

    OK(200),
    BAD_REQUEST(400),
    UNAUTHORIZED(401),
    FORBIDDEN(403),
    NOT_FOUND(404),
    NOT_ACCEPTABLE(406),
    CONFLICT(409),
    INTERNAL_SERVER_ERROR(500);

    private Integer value;

    ResponseCode(Integer value) {
        this.value = value;
    }

    public Integer getValue(){
        return value;
    }
}

package cn.qingtian.knife4j.response;

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

import java.io.Serializable;

@Data
@ApiModel("通用业务响应数据")
public class JsonResult<T> implements Serializable {
    // 业务返回码
    @ApiModelProperty(name = "state",value = "业务返回码",example = "401 402 403", position = 1)
    private Integer state;
    // 业务消息
    @ApiModelProperty(name = "message",value = "业务消息",example = "请求参数格式错误, 密码错误",position = 2)
    private String message;
    // 业务数据
    @ApiModelProperty(name = "data",value = "业务数据",example = "3")
    private T data;
    // 构造方法私有化, 限制此类创建规则
    private JsonResult(){}
    // 处理成功返回结果
    public static <T> JsonResult<T> ok(T data){
        JsonResult<T> jsonResult = new JsonResult<>();
        jsonResult.state = ResponseCode.OK.getValue();
        jsonResult.data = data;
        return jsonResult;
    }
    public static JsonResult<Void> ok(String message){
        JsonResult<Void> jsonResult = new JsonResult<>();
        jsonResult.state = ResponseCode.OK.getValue();
        jsonResult.message = message;
        return jsonResult;
    }
    // 处理成功返回结果, 没有返回消息和返回数据
    public static JsonResult<Void> ok(){
        return ok(null);
    }
    // 处理失败返回的结果, 返回结果一般有错误信息和业务返回码, 不包含处理数据结果
    public static JsonResult<Void> fail(ResponseCode state, String message){
        JsonResult<Void> jsonResult = new JsonResult<>();
        jsonResult.state = state.getValue();
        jsonResult.message = message;
        return jsonResult;
    }
}

在cn.qingtian.knife4j下创建包controller, 并创建以下类

package cn.qingtian.knife4j.controller;

import cn.qingtian.knife4j.pojo.dto.UserDTO;
import cn.qingtian.knife4j.pojo.vo.UserVO;
import cn.qingtian.knife4j.response.JsonResult;
import com.github.xiaoymin.knife4j.annotations.ApiOperationSupport;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

@RestController
@RequestMapping("/user")
@Api(tags = "1. 用户管理模块")
public class UserController {

    @ApiOperation(value = "增加用户")
    @ApiOperationSupport(order = 10)
    @PostMapping("/add-new")
    public UserVO addNew(UserDTO userDTO){
        UserVO userVO = new UserVO();
        userVO.setUsername("root");
        userVO.setPassword("root");
        return userVO;
    }

    @ApiOperation(value = "删除用户")
    @ApiOperationSupport(order = 20)
    @ApiImplicitParam(name = "userId",value = "用户id",required = true,dataType = "long",example = "1")
    @DeleteMapping("/delete/{userId}")
    public JsonResult delete(@PathVariable Long userId){
        return JsonResult.ok();
    }

    @ApiOperation(value = "修改用户")
    @ApiOperationSupport(order = 30)
    @ApiImplicitParams(
            @ApiImplicitParam(name = "userId",value = "用户id",required = true,dataType = "long",example = "1")
    )
    @PutMapping("/update/{userId}")
    public JsonResult update(@PathVariable Long userId, UserDTO userDTO){
        return JsonResult.ok();
    }

    @ApiOperation(value = "查询用户列表")
    @ApiOperationSupport(order = 40)
    @GetMapping("/list")
    public JsonResult list(){
        List<UserVO> list = new ArrayList<>();
        UserVO userVO = new UserVO();
        userVO.setUsername("root");
        userVO.setPassword("root");
        list.add(userVO);
        return JsonResult.ok(list);
    }
}

启动项目,效果:

1. 增加用户

2. 删除用户

3. 修改用户


4. 查询用户列表

五、其它

1. 生成本地API文件

在线API文档导出到本地

2. 全局参数设置

通过全局参数设置可以, 可以设置cookie等, 调试发送请求时, 会携带此请求头

---