前端同事老是说swagger不好用，我用了knife4j后，同事爽得不行

日常开发当中，少不了前端联调，随着协同开发的发展，前端对接口要求也变得越来越高了。所以我使用了knife4j ，同事用完觉得太舒服了。

knife4j简介：

Knife4j的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目。

2.0.2 版本需要代码加入注解引入依赖：

@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)

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

2.0.6版本直接加到yml配置当中

spring:
  knife4j:
  enable: true

关于个性化文档(knife4j.documents)以及个性化设置(knife4j.setting),有一些细微的区别,开发者在配置文件中进行配合好后,还需要在创建Docket对象时调用Knife4j提供的扩展Extesions进行赋值。

后台config配置：

import org.springframework.boot.autoconfigure.condition.ConditionalOnExpression;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

/**
 * 接口配置
 * @author yang
 * @since
 */
@Configuration
@EnableSwagger2
public class SearchSwaggerConfig {

    @Bean
    @ConditionalOnExpression("'${spring.profiles.active}'=='local' || '${spring.profiles.active}'=='dev' || '${spring.profiles.active}'=='isstest'")
    public Docket createRestApi() {
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        tokenPar.name("x-token").description("token令牌:Bearer").defaultValue("Bearer ").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
        pars.add(tokenPar.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xy.cloud.search.controller"))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars)
                .apiInfo(apiInfo());

    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("搜索文档中心 API")
                .version("v1")
                .build();
    }
}

常用注解使用：

@Api()
作用在类上，用来标注该类具体实现内容。
参数：
tags：类标签，一般用来写类的名称或作用。（常用）
description：可描述描述该类作用。

@ApiOperation()
用于方法的说明
参数：
value ：方法说明（常用）
notes ：注释说明
httpMethod ： 说明这个方法被请求的方式
response ：方法的返回值的类型

@ApiOperationSupport()
（knife4j增加特性）用于接口方法排序，作者信息描述等。
参数：
order：排序
author：作者信息

@ApiImplicitParam()
对单个参数的说明
参数：
name ：参数名。
value ： 参数的具体意义，作用。（常用）
required ： 参数是否必填。 （常用）
dataType ：参数的数据类型。 （常用）
paramType ：查询参数类型，这里有几种形式：
类型　　　　　作用
path 　　　以地址的形式提交数据
query 　　直接跟参数完成自动映射赋值
body　　　以流的形式提交 仅支持POST
header　　参数在request headers 里边提交
form　　　以form表单的形式提交 仅支持POST

@ApiModel()
用于描述一个数据模型的信息，即我们常用的实体、VO类、DTO类等描述
参数：
value ： 数据模型名称。（常用）
description:具体描述
parent：父类

@ApiModelProperty()
用于描述数据模型的属性信息
参数：
value：字段说明 （常用）
name：重写属性名字
dataType：重写属性类型
required：是否必填 （常用）
example：举例说明 （常用）
hidden：隐藏

@ApiIgnore
自动生成接口说明时忽略

类：

@Api(value = "搜索中心中文api")

方法：

@ApiOperation(value="查询信息",notes="查询信息",httpMethod="POST")
@ApiImplicitParam(name = "DirectoryDto" ,value ="文档dto",dataType ="json",required = false)

实体：

@ApiModel("文档dto 返回实体")

实体属性：

@ApiModelProperty(value = "搜索名称",dataType = "String",required=true)
private String name;

@ApiModelProperty(value = "主键id",dataType = "String",required=false)
private String  id;

@ApiModelProperty(value = "地址",dataType = "String",required=false)
private String  address;

@ApiModelProperty(value = "标题",dataType = "String",required=false)
private String  title;
@ApiModelProperty(value = "版本号",dataType = "String",required=false)
private String   version;

@ApiModelProperty(value = "手册目录id",dataType = "String",required=false)
private String  parentId;

访问地址：
http://192.168.192.1:9092/doc.html

对比一下ul 页面支持调试，下载，离线文档操作实在是太爽了：

明显上面页面操作调试都比下面好看，其实knife4j就是基于swagger的延伸。用了knife4j同事还想用，因为确实很爽，过后在也没有问过我字段什么意思。