在后端项目中,难免遇到需要写接口文档方便第三方调用的场景,一般业界最常用的方案是使用swagger。Java项目中,一般采用springfox项目,它集成了swagger和swagger-ui,不需要单独部署项目,可让文档随着项目一起发布。
但是开源项目往往是开源一时热,事后拂衣去,缺少维护。这个项目已经两年多没有维护了,很多人在issue反馈过bug,作者一年前表示自己比较忙,没空维护。
springfox最新的版本是2.9.2,不支持spring5(虽然有个快照版支持spring5,但一直没发布,整合也有点麻烦)。spring5比较大的一个改变就是增加了webflux,因此旧版springfox无法兼容spring5的。
其实用快照版,稍作修改也能让springfox支持webflux,但是我不是很喜欢这种做法。一个是增加了打包体积和运行内存占用,另一个则是swagger的使用污染了Java源码,很是不美观,强迫症不能忍。
@RestController
@RequestMapping("/dataspace/api/v1/hive")
@Api(value = "hive", description = "hive资源管理")
public class HiveManagerController {
@Autowired
HiveManagerService hiveManagerService;
@RequestMapping(value = "/list", method = {RequestMethod.POST})
@ApiOperation(value = "资源列表", notes = "")
public PageResult<HiveVO> showPublic(@ApiParam(value = "hive查询对象")
@RequestBody PageReqParam<HiveReq> hiveReq) {
result = hiveManagerService.getList(hiveReq);
return result;
}
源码中混入了各种ApiParam、Api、ApiOperation注解。
再加上我现在使用的springcloud套件,需要在gateway的feign接口上加注释,这样的话,无论是springfox,还是很多第三方的api doc工具都很难胜任。
于是,我想到了另外一种方法,就是javadoc。然而javadoc自带的注解很有限,不能满足第三方对文档的需求,比如
/**
* 根据节点名删除主机
* @method DELETE
* @path host/delHostByNodeName
* @param nodeName 节点名
* @param cluster 集群名
* @return JSON
*/
@DeleteMapping("/delHostByNodeName")
public String delHostByNodeName(@RequestParam("nodeName") String nodeName,@RequestParam("cluster") String cluster);
javadoc并不认识method和path这两个注解,生成的文档还是缺少一些必须要的信息。
这个不难,扩展下taglet即可。
先引入maven依赖
<dependency>
<groupId>jdk.tools</groupId>
<artifactId>jdk.tools</artifactId>
<version>1.8</version>
<scope>system</scope>
<systemPath>${JAVA_HOME}/lib/tools.jar</systemPath>
</dependency>
扩展taglet代码
package com.github.cloud.ali.common.tool;
import com.sun.javadoc.Tag;
import com.sun.tools.doclets.Taglet;
import java.util.Map;
public class MethodTaglet implements Taglet {
private String NAME = "HTTP请求类型";
private String HEADER = "HTTP请求类型:";
@Override
public boolean inField() {
return false;
}
@Override
public boolean inConstructor() {
return false;
}
@Override
public boolean inMethod() {
return true;
}
@Override
public boolean inOverview() {
return true;
}
@Override
public boolean inPackage() {
return true;
}
@Override
public boolean inType() {
return true;
}
@Override
public boolean isInlineTag() {
return false;
}
@Override
public String getName() {
return NAME;
}
@Override
public String toString(Tag tag) {
return "<DT><B>" + HEADER + "</B><DD>"
+ "<table cellpadding=2 cellspacing=0><tr><td bgcolor=\"yellow\">"
+ tag.text()
+ "</td></tr></table></DD>\n";
}
@Override
public String toString(Tag[] tags) {
return "";
}
}
同理,path注解也是类似的实现。编译命令如下:
javadoc -protected -splitindex -use -author -version -encoding utf-8 -charset utf-8 -d /usr/jackma/doc -windowtitle "ali 文档" $(ls /usr/jackma/ali/ali-common/src/main/java/com/github/cloud/ali/common/model/*.java |tr "\n" " ") $(ls /usr/jackma/ali/ali-gateway/src/main/java/com/github/cloud/ali/feign/*.java |tr "\n" " ") -tag method:a:"HTTP请求方法:" -tag path:a:"请求路径:" -tagletpath /usr/jackma/ali/ali-common/src/main/java/com/github/cloud/ali/common/tool/MethodTaglet.java -tagletpath /usr/jackma/ali/ali-common/src/main/java/com/github/cloud/ali/common/tool/PathTaglet.java -taglet com.github.cloud.ali.common.tool.MethodTaglet -taglet com.github.cloud.ali.common.tool.PathTaglet
其实就是在javadoc这个JDK自带工具的命令里加上了taglet参数,指定了自定义注解。
最终效果如下:
增强版javadoc
可以看到,文档内容更详细,显示也更美观了。
还可以进一步,加上数据类型的注解,这样就更完善了。
虽然离swagger-ui还有点差距,但是比原版javadoc好多了。最大的优点是没有任何限制和对源码的污染。
不得不说,Java的扩展性确实很好。
swagger-ui优点:
1.集成度高,文档随项目一期发布
2.文档内容详细,并且带有调试工具
3.可导出json文件,界面可自定义
swagger-ui缺点:
1.引入第三方依赖,增加打包体积和运行内存
2.兼容性差,无法通用于所有Java项目
3.对源码有侵入,污染Java源代码
4.缺乏维护和更新
扩展javadoc优点:
1.源码无侵入
2.扩展性强,兼容性高
扩展javadoc缺点:
1.界面不够美观,文档不具有通用性
2.需要手工维护文档生成命令
来源:
https://www.toutiao.com/i6826193228912394755/
“IT大咖说”欢迎广大技术人员投稿,投稿邮箱:aliang@itdks.com
来都来了,走啥走,留个言呗~
IT大咖说 | 关于版权
由“IT大咖说(ID:itdakashuo)”原创的文章,转载时请注明作者、出处及微信公众号。投稿、约稿、转载请加微信:ITDKS10(备注:投稿),茉莉小姐姐会及时与您联系!
感谢您对IT大咖说的热心支持!