从0开始springboot后台管理项目--集成knife4j（文档说明工具）

1.什么是knife4j

官网介绍： knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案

简单来说就是一个借口文档+调试工具，相当于swagger的一个升级版。页面更好看，功能更强大，支持微服务等。

官网地址：knife4j

2.使用knife4j

2.1修改pom.xml

这里使用当前官网最新办的2.0.9。

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

2.2配置文件

目录结构：

配置文件：

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
 
    @Bean
    public Docket docket(Environment environment) {
        // 添加接口请求头参数配置 没有的话 可以忽略
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("token")
                .description("令牌")
                .defaultValue("")
                .modelRef(new ModelRef("string"))
                .parameterType("header").required(false).build();
        pars.add(tokenPar.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否启动swagger 默认启动
                .enable(true)
                //所在分组
                .groupName("snail")
                .select()
                //指定扫描的包路径
                .apis(RequestHandlerSelectors.basePackage("com.monkey.snail.modules"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }
 
    private ApiInfo apiInfo() {
        Contact author = new Contact("李某人", "山东省烟台市", "1198025944@qq.com");
        return new ApiInfo(
                "snail文档",
                "snail文档",
                "1.0",
                "",
                author,
                "",
                "",
                new ArrayList()
        );
    }
}

经过上述配置我们已经可以启动项目，访问地址：http://localhost:8080/doc.html就可以看到knife4j的页面了，相对于swaggerUI界面确实好看不少。

2.3编写测试类

编写两个测试请求,一个get方法一个post方法。

TestController：

@Api(tags = "测试类")
@RestController
@RequestMapping("/test")
public class TestController {
 
    @ApiOperation("测试get方法")
    @ApiImplicitParam(name = "name", value = "姓名", required = true)
    @GetMapping("testGet")
    public String testGet(@RequestParam(value = "name") String name) {
        return "hello," + name;
    }
 
    @ApiOperation("测试post+实体类入参")
    @ApiOperationSupport(author = "ceshi")
    @PostMapping("testPost")
    public String testPost(@RequestBody TestDemo testDemo) {
        return testDemo.getName() + ":" + testDemo.getSex();
    }
}

TestDemo：

@ApiModel
@Data
public class TestDemo {
 
    @ApiModelProperty(value = "姓名", required = true)
    private String name;
    @ApiModelProperty(value = "性别", required = true)
    private String sex;
}

注意：路径要放在配置文件RequestHandlerSelectors.basePackage的配置路径下，否则无法扫描出。重新启动项目可以看到对应的接口信息。并可以在线完成调试等。至此knife4j基本功能已经完成。如果项目存在拦截器需要放行该路径。

 2.4增强模式

增强模式下增加了很多新的功能，比如：

接口添加作者	增加接口作者名称以及排序功能
自定义文档	如果knife4j不足以满足接口说明可以通过Markdown自定义说明
访问权限控制	生产环境屏蔽/页面权限控制
动态请求添加文档	为一些动态的MAP/JSON等添加说明

增强模式下还有不少功能，可以参考官方文档进行配置。

增强模式的开启需要在application.yml文件中添加：

knife4j:
  #是否开启增强模式 默认false
  enable: true

2.5注解说明

knife4j中几个核心注解以及参数说明：

@ApiModel

        使用场景：作用在实体类上。

        主要属性说明：

                value：自定义类名称

                description:为类添加说明

@ApiModel(value = "测试类",description = "测试工具使用")

@ApiModelProperty

        使用场景：实体类的具体参数上

        主要属性说明：

                value：参数描述

                name：参数名称

                required：是否必传

                allowEmptyValue：是否允许为空

@ApiModelProperty(value = "姓名", required = true , name = "姓名" , allowEmptyValue = true )
private String name;

@Api：

        使用场景：controller层类上

        主要属性说明：

                tags:分组，可以传入多个值，在多个分组会同时显示

@Api(tags = "测试类")

@ApiOperation

        使用场景：controller层具体接口上，用来概述方法作用

@ApiOperationSupport

        使用场景：controller层具体接口上（加强版用）

        主要属性说明：

                author：添加作者

                order：排序

@ApiOperation("测试post+实体类入参")
@ApiOperationSupport(author = "ceshi",order =01 )