knife4j

这是对官网内容的一份总结，是对官网内容的整理
本文中所使用knife4j版本号–>2.0.8

简介

knife4j是springfox-swagger的增强UI实现，为Java开发者在使用Swagger的时候，能拥有一份简洁、强大的接口文档体验,前身是swagger-bootstrap-ui
官方指南

整合SpringBoot

添加依赖

在pom.xml中添加依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--在引用时请在maven中央仓库搜索最新版本号-->
    <version>2.0.8</version>
</dependency>

TIP:
3.x的版本依赖springfox3.0.0，springfox3.0目前也只更新发布了一个版本，从功能稳定性来说，可能不如2.x系列，所以开发者慎重使用，当然,如果是Ui上的一些功能性问题或者Bug，也欢迎开发者向Knife4j发起ISSUE (opens new window)，等springfox3版本趋于稳定后，knife4j的2.x版本就不会在更新，会并向3.x

添加配置文件SwaggerConfiguration.java


@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {

    @Bean(value = "defaultApi")
    public Docket defaultApi() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //分组名称
                .groupName("2.X版本")
                .directModelSubstitute(ObjectId.class, String.class)
                .select()
                // 添加方法上标注了@ApiOperation注解的类
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("knife4j")
                .description("knife4j文档")
                .termsOfServiceUrl("")
                .contact(new Concat("失铭","www.shiming.online","xshiming@foxmail.com"))
                .version("1.0")
                .build();
    }
}

Knife4j的使用

具体使用见–>官方指南

启动增强模式

配置文件中添加knife4j.enable=true

给接口加上作者

@RestController
@ApiSupport(author = "xshiming",order = 2)
@Api(tags = "knife4j测试")
public class TestController {

}

例：

使用@ApiSupport即可为模块设置author(作者)和order(排序)

接口排序

目前有两种排序方式

controller排序
controller下的接口排序

tags分组排序

使用@ApiSupport排序

@Api(tags = "2.0.3版本-20200312")
@ApiSupport(order = 284)
@RestController
@RequestMapping("/api/nxew203")
public class Api203Constroller {


}

使用@ApiSort排序

@Api(tags = "2.0.2版本-20200226")
@ApiSort(286)
@RestController
@RequestMapping("/api/nxew202")
public class Api202Controller {


}

使用@Api的position属性排序

@Api(tags = "2.0.2版本-20200226",position = 286)
@RestController
@RequestMapping("/api/nxew202")
public class Api202Controller {


}

官方推荐：@ApiSupport>@ApiSort>@Api

tag下接口排序

使用@ApiOperationSupport中的order字段排序

@ApiOperationSupport(order = 33)
@ApiOperation(value = "忽略参数值-Form类型")
@PostMapping("/ex")
public Rest<LongUser> findAll(LongUser longUser) {
    Rest<LongUser> r=new Rest<>();
    r.setData(longUser);
    return r;
}

过滤请求参数

一级参数

过滤实体类中不需要的属性

过滤单个属性ignoreParameters={"id"}
过滤多层次属性{"uptModel.id","uptModel.uptPo.id"}
过滤列表中属性ignoreParameters={"uptModel.uptPo[0].id"}

@ApiOperation(value = "新增Model接口1")
@ApiOperationSupport(ignoreParameters = {"id","orderDate.id"})
@PostMapping("/insertMode1l")
public Rest<UptModel> insertModel1(UptModel uptModel){
    Rest<UptModel> r =new Rest<>();
    r.setData(uptModel);
    return r;
}

json格式

json格式需要加上参数名称

@ApiOperation(value = "新增Model接口")
@ApiOperationSupport(ignoreParameters = {"uptModel.id","uptModel.name","uptModel.orderDate.id"})
@PostMapping("/insertModel")
public Rest<UptModel> insertModel(@RequestBody UptModel uptModel){
    Rest<UptModel> r =new Rest<>();
    r.setData(uptModel);
    return r;
}

包含请求参数

与过滤请求参数取反，使用自定义增强注解ApiOperationSupport中的includeParameters属性,可以强制包含要显示的参数.去除多余的参数显示

示例

@ApiOperationSupport(order = 40,includeParameters = {"ignoreLabels","longUser.ids"})
@ApiOperation(value = "包含参数值-Form类型1")
@PostMapping("/ex1c")
public Rest<IgnoreP1> findAllc12(IgnoreP1 ignoreP1) {
    Rest<IgnoreP1> r=new Rest<>();
    r.setData(ignoreP1);
    return r;
}

json格式与过滤请求参数相同，需要加上参数名称

动态参数

用Map或者JSONObject接收或者返回数据时，显示参数注释

示例：

@PostMapping("/createOrder426")
@ApiOperation(value = "jdk-HashMap-动态创建显示参数-无@RequestBody")
@DynamicParameters(name = "CreateOrderHashMapModel",properties = {
        @DynamicParameter(name = "",value = "注解id",example = "X000111",required = true,dataTypeClass = Integer.class),
        @DynamicParameter(name = "name3",value = "订单编号-gson"),
        @DynamicParameter(name = "name1",value = "订单编号1-gson"),
})
public Rest<HashMap> createOrder1235332(@RequestBody HashMap map){
    Rest<HashMap> r=new Rest<>();
    r.setData(map);
    return r;
}

@DynamicParameters中有一个name属性,该值可以理解为一个类名,如果你赋予name属性值,那么请保证全局唯一,或者干脆不赋值,交给Knife4j自动生成一个全局唯一的name值

注意

不建议使用动态参数接收，从接口类传递Map等动态参数到service层，代码可读性和维护性都大大降低，不能简单直接的表达出需要那些参数

其他

请求参数缓存：如果后端有默认值，缓存不会产生，而对于未设置默认值的方法，将缓存上一次输入的数据
动态请求参数：任意数量的请求参数
版本控制：后端新增接口或者接口编辑后，在ui界面显示更新标志（蓝色徽标）
到处离线文档：可以导出为Markdown，html，word，pdf四种格式
清除缓存：解决灵异问题
搜索Api：搜索接口地址，接口名称，接口描述
自定义host:跨域
访问权限控制：生产环境时屏蔽swagger：knife4j.production=true
自定义文档：自定义md文件扩充系统说明官网说明

Swagger常用注解

1. @Api

@Api作用在类上，说明一个类的作用。标记一个Controller类作为Swagger资源

1	@Api(value = "/user", description = "Description about user")

属性名称	作用
value	帮助理解，无意义
tags	ui界面模块名
description	对类的描述

2. @ApiOperation

@ApiOperation作用在方法上，说明方法的作用，每一个url资源的定义

1	@ApiOperation(value = "value值", notes = "说明",httpMethod = "GET")

属性名称	作用
value	方法的用途、作用
notes	接口说明
httpMethod	接口请求方式
response	接口返回参数类型

@ApiOperation中httpMethod的请求方式和@RequestMapping中method的请求方式不同，swagger则优先读取@ApiOperation中的请求方式.

3. @ApiParam()

@ApiParam()用于方式方法，是对参数的说明，与Controller中的方法并列使用

1	public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true) User user)

属性名称	作用
name	参数名
value	说明
required	是否必填

该注解如果用于实体类的方法中，则涉及该类的所有接口，对应的属性都会受相关的控制。

4. @ApiImplicitParam()

@ApiImplicitParam()用于方法，表示单独的请求参数

属性名称	作用
name	参数名
value	参数说明
dataTyp	数据类型,只有String/Integer
defaultValue	默认值
require	是否必要
paramType	参数位置
example	举例说明

5. @ApiImplicitParams()

@ApiImplicitParams()用于方法，包含多个@ApiImplicitParam()

6. @ApiModel

@ApiModel用于类

7. @ApiModelProperty()

@ApiModelProperty()用于方法，字段，表示对model属性的说明或者数据操作更改。

1	@ApiModelProperty(value = "名称", name="name2",dataType = "Java.lang.Integer")

属性名称	作用
value	字段
name	重写属性名字
dataType	重写属性类型
required	是否必填
example	举例说明
hidden	隐藏

8. @ApiIgnore()

@ApiIgnore用于类，方法，方法参数，不在Swagger上显示

报错

我在使用2.0.3版本knife4j时，后台接收参数运行程序控制台会报错，新版本中已解决

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is com.google.common.util.concurrent.ExecutionError: java.lang.NoSuchMethodError: com.google.common.collect.FluentIterable.concat(Ljava/lang/Iterable;Ljava/lang/Iterable;)Lcom/google/common/collect/FluentIterable;

解决方案：

<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>2.0.1.Final</version>
</dependency>

<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>7.0.0.Alpha6</version>
</dependency>

搜到的原因是因为hibernate和validation版本冲突，所以上面两个依赖任选其一更新即可

使用Swagger2

因为上诉错误，所以改用Swagger2

将knife4j依赖修改为：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>