使用knife接口文档生成器详细教程

knife Gitee 地址：https://gitee.com/xiaoym/knife4j

一、接口生成器 knife 介绍

在之前的项目中一直使用 swagger 生成后台接口文档，很好用，至少比之前用 word 写接口文档 postman 调试接口方便多了。swagger 提供了一套前端页面，但是需要在代码中加入注解，如： @Api @ApiOperation 等，耦合度比较高，但使用起来很方便。对我强迫症的我来说，swagger-ui 页面奇丑无比，给我的感觉就是特别乱，并且没办法保存常用的参数，使用起来很不方便。

这篇文章来介绍 knife，是 swagger 的增强版，同一个作者开发。该UI增强包主要包括两大核心功能：文档说明 和 在线调试

• 文档说明：根据Swagger的规范说明，详细列出接口文档的说明，包括接口地址、类型、请求示例、请求参数、响应示例、响应参数、响应码等信息，使用 knife 能根据该文档说明，对该接口的使用情况一目了然。
• 在线调试：提供在线接口联调的强大功能，自动解析当前接口参数,同时包含表单验证，调用参数可返回接口响应内容、headers、Curl请求命令实例、响应时间、响应状态码等信息，帮助开发者在线调试，而不必通过其他测试工具测试接口是否正确，简介、强大。并且可以实现缓存请求参数，设置header 或 query 全局参数和值。

二、效果图

三、SpringBoot整合knife

3.1 pom.xml的文件依赖

由于是 springfox-swagger 的增强UI包,所以基础功能依然依赖 swagger，springfox-swagger 的 jar 包必须引入。然后引入 knife4j-spring-ui 替代原来的 swagger-ui。

<!--Swagger2配置-->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>3.0.0</version>
		</dependency>
		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>knife4j-spring-boot-starter</artifactId>
			<version>3.0.3</version>
		</dependency>
		<!--Swagger-UI-->
		<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>knife4j-spring-ui</artifactId>
			<version>3.0.3</version>
		</dependency>

3.2 编写Swagger2Config配置文件

package com.rich.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
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.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.Contact;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

/**
 * Created by IntelliJ IDEA.
 * Author: Rich
 * Date: 2021/8/3 9:59
 * Description: Swagger2配置类
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
public class Swagger2Config {

	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.host("http://localhost:8081")
				.apiInfo(apiInfo())
				.select()
				.apis(RequestHandlerSelectors.basePackage("com.rich.controller"))
				.paths(PathSelectors.any())
				.build()
	}

	public ApiInfo apiInfo(){
		return new ApiInfoBuilder()
				.title("Rich's Blog接口文档")
				.description("Rich's Blog接口文档")
				.contact(new Contact("Rich","http://localhost:8081/doc.html","501049950@qq.com"))
				.version("1.0")
				.build();
	}

}

访问地址，knife 默认访问地址是：http://${host}:${port}/doc.html

3.3 注意事项

SpringBoot 中访问 doc.html 或 swagger-ui.html 报404的解决办法
配置拦截器

@Configuration
public class IntercpetorConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 设置swagger静态资源访问
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

更多的接口文档

yapi