SpringBoot集成knif4j创建在线API文档

一直以来能够创建一个同项目一起发布的在线文档，曾经是很多程序员的梦想，偶然发现这个工具已经有了，测试之后发现还挺好用的，特地纪念。

这个工具就是knife4j，它是为Java MVC框架集成Swagger 生成Api文档的增强解决方案，其前身是swagger-bootstrap-ui。推荐采用了swagger的新增强版knife4j来生成API接口文档。knife4j的使用方法和swagger几完全一样。

1.引入pom.xml依赖：

<!--（老版本）引用依赖包-->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.6</version>
</dependency><!--（新版本）swagger增强工具依赖包，方便生成接口文档。非必须导入-->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.1</version>
</dependency>

2.配置SwaggerConfig类：

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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).pathMapping("/").select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build();}private ApiInfo apiInfo(){return new ApiInfoBuilder().title("SpringBoot 测试项目").description("This is a restful api document of").description("SpringBoot整合Swagger，详细信息......").version("1.0").contact(new Contact("作者","blog.csdn.net","xxxxxxx@qq.com")).license("Home").licenseUrl("http://localhost:9090/swagger-ui.html").build();}
}

可以看到，内容上和以前的swagger配置类一致的，唯一的变化是类注解需要比原来的swagger多加一个 @EnableSwaggerBootstrapUi。这样knife4j的所有配置都完成了。

以上有两个注解需要特别说明，如下：

@EnableSwagger2
这个注解是Springfox-swagger框架提供的使用Swagger注解，该注解不可以省略

@EnableKnife4j
这个注解是knife4j提供的增强注解,Ui提供了例如动态参数、参数过滤、接口排序等增强功能,
如果你想使用这些增强功能就必须加该注解，否则可以不用加

3.在Controller上增加注解

@Api(tags = "统一异常处理测试接口")
@RestController
@RequestMapping(value="/api")
public class UserRestController {@ApiOperation(value = "新增用户",notes="新增用户,post 方式")@PostMapping("/user")public boolean insert(@RequestBody User user) {System.out.println("开始新增...");//如果姓名为空就手动抛出一个自定义的异常！if(null == user.getUsername()){throw  new BizException("-1","用户姓名不能为空！");}return true;}@ApiOperation(value = "查询用户列表",notes="查询用户列表 get 方式")@GetMapping("/users")public ResultBody findByUser(User user) {System.out.println("开始查询...");List<User> userList = new ArrayList<>();User user2 = null;for(int i=0; i<10; i++) {user2 = new User();user2.setId("user_"+i);user2.setUsername("username_"+i);user2.setNickname("laowu "+i);userList.add(user2);}return ResultBody.success(userList);}

上面就是一个普通的Controller，里面用到了2个注解：

@Api(tags = "统一异常处理测试接口")， 这个注解是类级别的注解，里面的参数tags里面其实是对当前类的功能做概况说明
@ApiOperation(value = "新增用户",notes="新增用户,post 方式")
这个ApiOperation注解是方法级的注解，是对当前的方法的功能做介绍说明，

其实swagger有很多注解，常用的是这些：

Api Api 用在类上，说明该类的作用
ApiModel 描述一个Model的信息
ApiModelProperty 描述一个model的属性。
ApiOperation 用在方法上，说明方法的作用
ApiParam 请求属性
ApiResponse 响应配置
ApiResponses 响应集配置
ResponseHeader 响应头设置

4.在SpringBoot启动类上增加注解

@SpringBootApplication
@EnableSwagger2
public class Application {public static void main(String[] args) {SpringApplication.run(Application.class, args);}
}

SpringBoot启动类上需要增加@EnableSwagger2这个注解。

配置了这么多，该看看运行起来的效果了，运行springboot项目，自动生成接口文档，

访问在线API文档地址： http://localhost:8080/doc.html

访问swagger的地址： http://localhost:8080/swagger-ui.html

这样看起来是不是比普通的Sawgger看起来功能更完善了？左侧的导航栏可以列出当前工程里面所有的控制器，以及所有添加了Swagger注解的类。

还可以做接口测试：

比如我打开了统一异常处理测试接口这个控制器，下面会列出新增用户何查询用户列表两个方法，还贴心的列出类这里handler的请求方式，然后在右侧会打开一个标签页，标题就是这个handler注解，

@ApiOperation(value = "查询用户列表",notes="查询用户列表 get 方式")
是ApiOperation注解里面value里面的内容

在这个大标签页里面会有两个小的标签页，分别是文档和测试，默认打开的是文档这个标签页，这个标签页里是当前handler方法的比较详细的描述，接口描述的内容就是ApiOperation注解里面notes参数的值，因此在实际情况下应该把这个参数的内容写的更完善一些，测试时看起来就比较完整了。

这里列出了
接口地址
请求方式
consumes
produces
接口描述
请求参数
响应状态
响应参数
响应示例
这个几个最常用到的项目。

点击右边的调试标签，打开这个接口的调试窗口

这个是完整的调试窗口，这里列出了这个接口参数的具体数据，点击发送就可以向后台发送请求，返回结果也是默认用比较美观的方式展示出来，同时还给出了响应内容、Raw、Headers、Curl 这几个功能

响应内容：是后台返回的经过美化的jsong格式
Raw：里面是原始的json数据
Headers: 请求头
Curl：Curl命令的具体参数，这个在Linux下测试接口非常有用

更贴心的一个功能，这里还提示类这个接口的执行时间

这个功能对于优化接口的性能很帮助。

相信看到这里的小伙伴对knif4j已经有了比较直观的认识，赶紧来试试吧。