介绍

概念：使用Swagger，只需要按照它的规范去定义接口及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面

Knife4i 是为Java MVC框架集成Swagger生成Api文档的增强解决方案

使用方式

  1. 导入Maven坐标：
1
2
3
4
5
<dependency>
  <groupld>com.github.xiaoymin</groupld>
  <artifactld>knife4j-spring-boot-starter</artifactld>
  <version>3.0.2</version>
</dependency>
  1. 在配置类中加入Knife4i相关配置：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
/**
 * 通过knife4j生成接口文档
 * @return
 */
@Bean
public Docket docket() {
    ApiInfo apiInfo = new ApiInfoBuilder()
            .title("苍穹外卖项目接口文档")
            .version("2.0")
            .description("苍穹外卖项目接口文档")
            .build();
    Docket docket = new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.sky.controller"))
            .paths(PathSelectors.any())
            .build();
    return docket;
}
  1. 在配置类中设置静态资源映射，否则接口文档页面无法访问：
1
2
3
4
5
6
7
8
9
/**
 * 设置静态资源映射
 * @param registry
 */
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}

常用注解

概念：通过注解可以控制生成的接口文档，使用接口文档拥有更好的可读性

注解 说明
@Api 用在类上，例如Controller包下的类，表示对类的说明
@ApiModel 用在类上，例如entity、DTO、VO
@ApiModelProperty 用在属性上，描述属性信息
@ApiOperation 用在方法上，例如Controller（控制层）中的方法，说明方法的用途、作用

@Api 注解中使用tags属性进行描述

@ApiModel 注解中使用description属性进行描述

@ApiModelProperty 注解中使用value属性进行描述

@ApiOpeartion 注解中使用value属性进行描述

分组生成接口文档

在配置类中配置多个Docket对象，并且为每个对象设置分组，分别扫描不同的包即可实现分组生成接口文档

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
/**
 * 通过knife4j生成管理端接口文档
 * @return
 */
@Bean
public Docket docket1() {
    ApiInfo apiInfo = new ApiInfoBuilder()
            .title("苍穹外卖项目接口文档")
            .version("2.0")
            .description("苍穹外卖项目接口文档")
            .build();
    Docket docket = new Docket(DocumentationType.SWAGGER_2)
            .groupName("管理端接口")
            .apiInfo(apiInfo)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.sky.controller.admin"))
            .paths(PathSelectors.any())
            .build();
    return docket;
}

/**
 * 通过knife4j生成用户端接口文档
 * @return
 */
@Bean
public Docket docket2() {
    ApiInfo apiInfo = new ApiInfoBuilder()
            .title("苍穹外卖项目接口文档")
            .version("2.0")
            .description("苍穹外卖项目接口文档")
            .build();
    Docket docket = new Docket(DocumentationType.SWAGGER_2)
            .groupName("用户端接口")
            .apiInfo(apiInfo)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.sky.controller.user"))
            .paths(PathSelectors.any())
            .build();
    return docket;
}