springboot项目集成java接口文档生成工具knife4j

knifie

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名kni4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍!

knife4j的前身是swagger-bootstrap-ui，为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j

开始

1、springboot项目只需要引入如下依赖即可

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

2、增加一个swagger配置类

package com.danseek.demo.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


/**
 * @Description: swagger配置类
 * @Author: danseek
 * @CreateTime: 2020-10-22 15:51
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
@Profile({"dev","test"})
public class SwaggerConfiguration {

    @Bean
    public Docket createRestApi() {
        return  new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .groupName("后端接⼝⽂档")
                .apiInfo(apiInfo())
                .select()
                //配置哪些路径和API会生成document
                .apis(RequestHandlerSelectors.basePackage("com.danseek.demo.controller"))
                .paths(PathSelectors.any())
                .build();

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口文档")
                .description("后台相关接口")
                .contact(new Contact("danseek",null,null))
                .version("1.0")
                .build();
    }

}

3、application.yml

server:
  port: 8090
  servlet:
    context-path: /

spring:
  application:
    name: Knife4j-Demo
  profiles:
    active: dev

搭建完成，启动项目访问：http://192.168.1.210:8090/doc.html

swagger注解

接下来给控制器和请求参数加上注解让生成的文档更易读

package com.danseek.demo.controller;

import com.danseek.demo.entity.User;
import com.github.xiaoymin.knife4j.annotations.DynamicParameter;
import com.github.xiaoymin.knife4j.annotations.DynamicParameters;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

/**
 * @Description: todo
 * @Author: danseek
 * @CreateTime: 2020-10-23 15:20
 */
@Api(value = "用户控制器",tags = "用户控制器")
@Slf4j
@RestController
@RequestMapping("/user")
public class UserController {

    @GetMapping("obj")
    // 设置接口标题、描述注解
    @ApiOperation(value = "对象参数",notes = "获取用户")
    // 如果请求参数是对象，只需要给user实体类的属性加上注解即可，这里不需要加
    public User obj(User user){

        User u = new User();
        u.setUserName("danseek");
        u.setMobile("13888888888");
        return u;
    }

    @GetMapping("obj1")
    @ApiOperation(value = "动态参数",notes = "获取用户")
    // 设置动态参数描述注解
    @DynamicParameters(name = "map",properties = {
            @DynamicParameter(name = "id",value = "id",example = "1",required =
                    true,dataTypeClass = Integer.class),
            @DynamicParameter(name = "userName",value = "用户名",required =true),
            @DynamicParameter(name = "mobile",value = "手机号"),
    })
    public User obj1( @RequestBody Map map){

        User u = new User();
        u.setUserName("danseek");
        u.setMobile("13888888888");
        return u;
    }

    @GetMapping("obj2")
    @ApiOperation(value = "静态参数",notes = "获取用户")
    // 设置参数描述注解
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "id", required = false, dataType =
                "integer", paramType = "query"),
        @ApiImplicitParam(name = "mobile", value = "手机号", required = false, dataType =
                    "string", paramType = "query"),
    })
    public User obj2(Integer id,String mobile){

        User u = new User();
        u.setId(id);
        u.setMobile(mobile);
        u.setUserName("danseek");
        u.setMobile("13888888888");
        return u;
    }
}

@ApiModelProperty给实体类参数加上注释

package com.danseek.demo.entity;

import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import lombok.EqualsAndHashCode;
import lombok.experimental.Accessors;

/**
 * 用户表
 * @author danseek
 * @CreateTime: 2020-10-23 15:25
 */
@Data
@EqualsAndHashCode(callSuper = false)
@Accessors(chain = true)
public class User {

    /**
     * 用户ID
     */
    @ApiModelProperty(value = "用户id",example = "1",required = false)
    private Integer id;


    /**
     * 登录用户名
     */
    @ApiModelProperty(value = "用户名",example = "admin",required = false)
    private String userName;

    /**
     * 密码
     */
    @ApiModelProperty(value = "密码",example = "123456",required = false)
    private String password;


    /**
     * 登录者名字
     */
    @ApiModelProperty(value = "用户姓名",example = "张三",required = false)
    private String realName;

    /**
     * 登录者手机
     */
    @ApiModelProperty(value = "手机",example = "13899999999",required = false)
    private String mobile;


}

如图，中文描述都是用注解配的

如果需要在所有请求参数中配置token，设置globalOperationParameters即可

@Bean
    public Docket createRestApi() {
        ParameterBuilder parameterBuilder=new ParameterBuilder();
        List<Parameter> parameters= Lists.newArrayList();
        parameterBuilder.name("token").description("token令牌").modelRef(new ModelRef("String"))
                .parameterType("header")
                .required(true).build();
        parameters.add(parameterBuilder.build());

        return  new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(true)
                .groupName("前后端接⼝⽂档")
                .apiInfo(apiInfo())
                .select()
                //选择哪些路径和API会生成document
                .apis(RequestHandlerSelectors.basePackage("com.jassonsoft.admin.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(parameters);
    }

文档中会显示

其他

1、隐藏某个请求参数使用@ApiIgnore注解在参数上

@ApiOperation(value = "文件上传")
    @ApiImplicitParams({@ApiImplicitParam(name = "file", value = "文件流对象",paramType="form", required = true,dataType = "__File"),
            @ApiImplicitParam(name = "md5FileName", value = "文件名称",paramType="query", required = true)}
    )
    @RequestMapping(value = "uploadFile", method = RequestMethod.POST)
    public ResponseVo uploadBanners(@ApiIgnore HttpServletRequest request, @ApiIgnore MultipartHttpServletRequest multipartReq){
        ResponseVo responseVo = new ResponseVo();
        .....
    }

这时需要使用@ApiImplicitParam 注解隐式地声明接口参数，否则页面不会显示参数

2、接口排序

@ApiSort(value = 5)：给接口排序

@ApiOperationSupport(order = 1)：给接口里面的方法排序

@ApiIgnore()：接口或方法不在页面显示

@Api(value = "数据分析",tags = "数据分析")
@ApiSort(value = 5)
@Slf4j
@RestController
@RequestMapping("/analysis")
public class AnalysisDataController extends BaseController{
        
        @ApiOperationSupport(value = "消息查询统计")
        @ApiSupport(order = 1)
        @RequestMapping(value = "getMessageQueryStatistics", method = RequestMethod.POST)
        public ResponseVo<Page> getMessageQueryStatistics(HttpServletRequest request, @RequestBody Map map) {
       ....
       }
}