在后端项目中，难免遇到需要写接口文档方便第三方调用的场景，一般业界最常用的方案是使用swagger。Java项目中，一般采用springfox项目，它集成了swagger和swagger-ui，不需要单独部署项目，可让文档随着项目一起发布。

为什么不使用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 showPublic(@ApiParam(value = "hive查询对象")                                          @RequestBody PageReqParam hiveReq) {        result = hiveManagerService.getList(hiveReq);        return result;    }

源码中混入了各种ApiParam、Api、ApiOperation注解。

再加上我现在使用的springcloud套件，需要在gateway的feign接口上加注释，这样的话，无论是springfox，还是很多第三方的api doc工具都很难胜任。

扩展JDK自带工具javadoc

于是，我想到了另外一种方法，就是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依赖

jdk.tools            jdk.tools            1.8system${JAVA_HOME}/lib/tools.jar

扩展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 "" + HEADER + ""                + "

" + tag.text() + ""; } @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 "" " ") $(ls /usr/jackma/ali/ali-gateway/src/main/java/com/github/cloud/ali/feign/*.java |tr "" " ") -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.需要手工维护文档生成命令