knife4j是本人用过的自动生成接口文档工具中最好用的,之前有用过JApiDocs和Swagger作为自动生成接口文档工具。但都没有knife4j的用得舒服。
1、下面是JApiDocs生成的接口文档,可以看到,虽然具备接口文档的用途,但相对于knife4j来说少了挺多东西的。
下面是knife4j生成的接口文档,对比起上面,页面好看了不少,而且功能也多了许多。
多了调试的功能,不用再去postman、apifox接口测试工具测试接口了
还可以通过四种方式下载到本地离线观看
2、 接下来介绍如何使用knife4j
(1)引入knife4j的依赖
只需要引入这一个接口文档依赖就可以了,多引入可能会冲突。
<!-- 接口文档-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
<version>4.1.0</version>
</dependency>
(2)在配置文件中开启knife4j
记得把这项配置放在配置文件的最后或较后面,否则可能会出现还没读到数据库配置就开始报错了。
#开启api文档
knife4j:
enable: true
(3)在各代码层加上相应的注解
不同于JApiDocs是通过注释来生成备注,knife4j通过注解来生成备注
这里介绍一下主要的注解,其他注解可以参考官方文档。具体效果可以自己尝试。
//controller层的类前注解
@Api(tags = "用户接口")
//controller层方法前注解和mapping无位置要求
@ApiOperation(value = "登录")
@PostMapping("/login")
//dto层属性前注解,也是参数属性注解
@ApiParam(value = "员工ID",required = true) String id
//model或vo层属性前注解
@ApiModelProperty(value = "日志id")
(4)然后启动项目
在浏览器中输入链接: http://localhost:端口号/doc.html,打开前可以确认一下会不会被拦截器拦截了,拦截了要放行才能看到。