在后端項目中，難免遇到需要寫接口文檔方便第三方調用的場景，一般業界最常用的方案是使用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.需要手工維護文檔生成命令

總結

以上是生活随笔為你收集整理的delphi ui编辑工具源码_一种无侵入比swagger-ui兼容性更好更简单的API文档生成方案的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。