Knife4j使用教程

Knife4j

是一个集Swagger2 和 OpenAPI3为一体的增强解决方案

Knife4j的优点

Knife4j 功能强大，易于操作。
Knife4j 的UI界面非常美观，使用非常流畅。
Knife4j 可以高度定制化，让其符合你的项目需求，提升用户体验。
Knife4j 的支持性比较好，可以满足大部分的开发需求

Knife4j快速上手

1.添加pom.xml依赖

<!--添加Knife4j依赖-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.1.0</version>
</dependency>

2.配置Swagger的相关信息

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // apiInfo()：配置 API 的一些基本信息，比如：文档标题title，文档描述description，文档版本号version
                .apiInfo(apiInfo())
                // select()：生成 API 文档的选择器，用于指定要生成哪些 API 文档
                .select()
                // apis()：指定要生成哪个包下的 API 文档
                .apis(RequestHandlerSelectors.basePackage("cn.tedu.weibo.controller"))
                // paths()：指定要生成哪个 URL 匹配模式下的 API 文档。这里使用 PathSelectors.any()，表示生成所有的 API 文档。
                .paths(PathSelectors.any())
                .build();
    }
    private static final String API_TILE="微博项目";
    //文档信息配置
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title(API_TILE)
                // 文档描述信息
                .description("微博项目在线API文档")
                // 文档版本号
                .version("1.0")
                .build();
    }
}

3.查看生成的接口文档
在 SpringBoot 项目启动后，访问 http://localhost:8080/doc.html 地址即可查看生成的Knife4j接口文档。

常用注解

1.@Api注解

添加在控制器类上的注解，通过此注解的tags属性可以修改原本显示控制器类名称的位置的文本，通常，建议在配置的tags属性值上添加序号，例如：“01. 用户模块”、“02. 微博模块”，则框架会根据值进行排序。
参数说明

tags：配置模块名称

2.@ApiOperation注解

添加在控制器类中处理请求的方法上的注解，用于配置此方法处理的请求在API文档中显示的文本。

参数说明

value：配置业务名称
3.@ApiModelProperty注解

是添加在POJO类的属性上的注解，用于对请求参数或响应结果中的某个属性进行说明，
主要通过其value属性配置描述文本，并可通过example属性配置示例值。

参数说明

value属性：配置参数名称
required属性：配置是否必须提交此请求参数
example属性：配置示例值
注意：如果配置了 required=true,只是一种显示效果，Knife4j框架并不具备检查功能

4.@ApiImplicitParam注解

添加在控制器类中处理请求的方法上的注解，主要用于配置非封装(非XxxDTO/XxxParam的参数)的参数

参数说明

name：指定参数名称（参数变量名）
value：配置参数名称
dataType：配置数据类型
required：配置是否必须提交此请求参数
example：配置参数的示例值
注意：一旦使用此注解，各个参数的数据类型默认都会显示String，可以通过dataType指定数据类型

5.@ApiImplicitParams注解

添加在控制器类中处理请求的方法上的注解，当方法有多个非封装的参数时，在方法上添加此注解，并在注解内部通过@ApiImplicitParam数组配置多个参数。

代码示例

此处以微博详情功能为例

@GetMapping("selectById")
@ApiOperation(value = "微博详情功能")
@ApiImplicitParams(value = {
    @ApiImplicitParam(name = "id", value = "微博", required=true, dataType = "int"),
    @ApiImplicitParam(name = "username", value = "用户名", required=true)
})
// 额外增加username参数，仅仅用于测试
public WeiboDetailVO selectById(int id, String username){
    return weiboMapper.selectById(id);
}

6.@ApiIgnore注解

添加在处理请求的方法的参数上，用于表示API文档框架应该忽略此参数

此处以发布微博功能的HttpSession参数为例

代码示例

// 参数中添加@ApiIgnore注解

public int insert(@RequestBody WeiboDTO weiboDTO, @ApiIgnore HttpSession session){}

导出离线文档

选择合适的文档格式，导出即可到本地磁盘