前端同事老是说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.enable	false	是否开启Knife4j增强模式
knife4j.cors	false	是否开启一个默认的跨域配置,该功能配合自定义Host使用
knife4j.production	false	是否开启生产环境保护策略,详情参考文档
knife4j.basic		对Knife4j提供的资源提供BasicHttp校验,保护文档
knife4j.basic.enable	false	关闭BasicHttp功能
knife4j.basic.username		basic用户名
knife4j.basic.password		basic密码
knife4j.documents		自定义文档集合，该属性是数组
knife4j.documents.group		所属分组
knife4j.documents.name		类似于接口中的tag,对于自定义文档的分组
knife4j.documents.locations		markdown文件路径,可以是一个文件夹(classpath:markdowns/*)，也可以是单个文件(classpath:md/sign.md)
knife4j.setting		前端Ui的个性化配置属性
knife4j.setting.enableAfterScript	true	调试Tab是否显示AfterScript功能,默认开启
knife4j.setting.language	zh-CN	Ui默认显示语言,目前主要有两种:中文(zh-CN)、英文(en-US)
knife4j.setting.enableSwaggerModels	true	是否显示界面中SwaggerModel功能
knife4j.setting.swaggerModelName	Swagger Models	重命名SwaggerModel名称,默认
knife4j.setting.enableDocumentManage	true	是否显示界面中"文档管理"功能
knife4j.setting.enableReloadCacheParameter	false	是否在每个Debug调试栏后显示刷新变量按钮,默认不显示
knife4j.setting.enableVersion	false	是否开启界面中对某接口的版本控制,如果开启，后端变化后Ui界面会存在小蓝点
knife4j.setting.enableRequestCache	true	是否开启请求参数缓存
knife4j.setting.enableFilterMultipartApis	false	针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,如果开启此配置,默认展示一个Post类型的接口地址
knife4j.setting.enableFilterMultipartApiMethodType	POST	具体接口的过滤类型
knife4j.setting.enableHost	false	是否启用Host
knife4j.setting.enableHomeCustom	false	是否开启自定义主页内容
knife4j.setting.homeCustomLocation		主页内容Markdown文件路径
knife4j.setting.enableSearch	false	是否禁用Ui界面中的搜索框
knife4j.setting.enableFooter	true	是否显示Footer
knife4j.setting.enableFooterCustom	false	是否开启自定义Footer
knife4j.setting.footerCustomContent	false	自定义Footer内容
knife4j.setting.enableDynamicParameter	false	是否开启动态参数调试功能
knife4j.setting.enableDebug	true	启用调试
knife4j.setting.enableOpenApi	true	显示OpenAPI规范
knife4j.setting.enableGroup	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同事还想用，因为确实很爽，过后在也没有问过我字段什么意思。