SpringBoot整合Knife4j(Swagger)

Knife4j是一款基于Swagger的增强工具(所以，该集成方式同样适用于swagger)，拥有更强的功能以及更符合大众审美观的UI。

Knife4j官网：https://doc.xiaominfo.com/knife4j/  (学习以及获取更多的功能用法、资讯一定要习惯去官网获取)

友情提示

借用官网一个友情提示

1、目前已经发行的Knife4j版本，Knife4j本身已经引入了springfox，开发者在使用时不用再单独引入Springfox的具体版本，否额会导致版本冲突。另外在网关层聚合(例如gateway)时，必须禁用Knife4j的增强模式；

2、使用Knife4j2.0.6及以上的版本，Spring Boot的版本必须大于等于2.2.x；

引入依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--选择适合自己SpringBoot版本的knife4j版本,具体版本坐标可在maven中央仓库搜索-->
    <version>1.9.6</version>
</dependency>

配置Knife4j

@Configuration
//knife4j依赖swagger:该注解也可直接加载启动类上
@EnableSwagger2
//支持knife4j的ui:该注解也可直接加载启动类上
@EnableSwaggerBootstrapUi
public class Knife4jConfig {

	@Bean
	public Docket initDocket() {

		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(createApiInfo()).select()
				// 扫描包:只扫描某个路径下带有Swagger注解的类,然后将其加入API文档
				// .apis(RequestHandlerSelectors.basePackage("com.zepal.rest.controller"))
				// 只扫描带有api注解的类
				// .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
				// 只扫描带有ApiOperation注解的方法
				.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
				// 对指定路径监控
				.paths(PathSelectors.any())
				.build();
	}

	private ApiInfo createApiInfo() {
		return new ApiInfoBuilder()
				// api文档的标题属性:会在api文档中相应显示
				.title("knife4j演示 V1.0")
				// api文档描述属性:会在api文档中相应显示
				.description("我是描述")
				// 服务url属性:会在api文档中相应显示
				.termsOfServiceUrl("http://localhost:9000/")
				// 自定义版本号属性:会在api文档中相应显示
				.version("1.0")
				.build();
	}
	
}

拦截器放行

如果项目中配置了拦截器，需要在注册拦截器时，将Knife4j相关的资源放行

@Override
    public void addInterceptors(InterceptorRegistry registry) {
		// 不拦截的请求
        List<String> patterns = new ArrayList<String>();
        patterns.add("/swagger-resources/**");
        patterns.add("/webjars/**");
        patterns.add("/v2/**");
        patterns.add("/swagger-ui.html/**");
        patterns.add("/doc.html/**");
        
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
      
        // swagger页面
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        // knife4j页面
		registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
		registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

    }

测试

访问本项目地址：localhos:port/doc.html出现如下界面：

Knife4j注解说明

避坑

避坑1：在使用相关注解时，所有注解的属性值不要出现英文点(".")，否则会导致无法识别，在api文档中也就不会出现相应接口信息。

心得

心得1：在为所有接口进行命名的时候，建议遵循该规则：模块:功能:细分功能，以冒号分隔开，"模块:功能"注解到Controller类上，"细分功能"注解到具体的接口上，命名具体划分几级，则根据项目具体情况而定。比如：购物车:商品管理:新增商品。这样在api文档中显示的接口信息比较直观。

@Api注解

该注解一般用于控制层的类名上，即Controller的类名上。该注解常用属性tags(如果用value属性，不会被解析)，用于说明该Controller的功能。

@ApiOperation

该注解一般用于具体的api接口上。该注解常用属性value，用于说明该api接口的功能，属性consumes，用于描述该接口接收的参数媒体类型。比如：application/json，application/xml，multipart/form-date，applictaion/x-www-form-urlencoded。consumes属性默认属性是"application/json"，所以，如果接口支持的请求参数媒体类型不是"application/json"，建议将该属性添加上，免得接口调用方传参不知道用什么媒体类型。

@ApiImplicitParam

该注解一般用于具体的api接口上，用于描述请求参数。属性name描述参数名，属性value描述参数说明，属性required描述参数是否必须，属性dataType描述参数类型。多个参数用@ApiImplicitParams嵌套，它支持@ApiImplicitParam数组。

一个完整的示例：

@Api(tags = "knife4j演示:")
@Controller
public class Knif4jController {

	@PostMapping("/knife4j_A")
	@ResponseBody
	@ApiOperation(value = "演示接口A", consumes = "applictaion/x-www-form-urlencoded,application/json")
	@ApiImplicitParams({
		@ApiImplicitParam(name = "username", value = "用户名", required = true, dataType = "string"),
		@ApiImplicitParam(name = "password", value = "密码", required = true, dataType = "string")
	})
	public String methodA(String username, String password) {
		// applictaion/x-www-form-urlencoded
		return "success";
	}
	
}

 重启项目后，可以在localhost:port/doc.html 文档页面中，看到接口信息，如下：

说明：示例没有定义响应对象，只是返回了一个String字符串，所以在api文档中看不到响应参数。

响应参数注解，以及使用自定对象封装请求参数

@ApiModel注解：注解到响应对象或请求对象类上，value属性用于描述该对象的名称

@ApiModelProperty注解：注解到请求对象或响应对象的属性上。value属性用于描述参数说明，dataType属性用于描述数据类型。required属性用于描述参数是否必须，一般用于请求对象，响应对象没有意义。

一个完整的示例：

@ApiModel(value = "测试请求对象")
public class TestVO implements Serializable {

	private static final long serialVersionUID = 1L;

	@ApiModelProperty(value = "用户名", dataType = "string", required = true)
	private String username;
	
	@ApiModelProperty(value = "密码", dataType = "string", required = true)
	private String password;

	public String getUsername() {
		return username;
	}

	public void setUsername(String username) {
		this.username = username;
	}

	public String getPassword() {
		return password;
	}

	public void setPassword(String password) {
		this.password = password;
	}
	
}