一個給 Java 程序員用的 Api 文檔生成工具

api 文檔做爲先後端同窗的溝通橋樑，其重要性是不言而喻的。目前通用的工具備像apidoc/apidoc，caixw/apidoc 這樣的第三方庫，雖然具備語言無關的特性，可是真正用起來額外多了不少工做量，並且維護起來麻煩，這也是筆者設計和開發這個工具的緣由，想經過 java 自己的語言特性和結合強大的 IDE ，使得生成和維護 api 文檔這件事情變的天然而美好。

簡介

github地址：JApiDocs

JApiDocs 是一個符合 Java 編程習慣的 Api 文檔生成工具。最大程度地利用 Java 的語法特性，你只管用心設計好接口，添加必要的註釋，JApiDocs 會幫你導出一份漂亮的 Html 文檔，並生成相關的 Java 和 Object-C 相關數據模型代碼，今後，Android 和 IOS 的同窗能夠少敲不少代碼了，你也不須要費力維護接口文檔的變化，只須要維護好你的代碼就能夠了。

特性

1. 以一個 Controller 做爲一組接口導出到一個 Html 文件中。
2. 支持生成 Java 和 Object-C 語言的 Response 模型代碼。
3. 深度支持 Spring Boot， PlayFramework，JFinal，不須要額外聲明路由。
4. 支持通常的 Java Web 工程，須要在相關方法添加額外的路由。
5. 支持接口聲明過期(@Deprecated)，方便的文檔目錄等。
6. 支持自定義代碼生成模板。

5分鐘集成

(1) 咱們以 spring 爲例，一張圖很容易就明白了 JApiDocs 是怎麼工做的了，你在設計接口的時候能夠順便就把相關的註釋給填好了，這和 Java 程序員的編程習慣是保持一致的。

這裏你可能會對@ApiDoc註解感到迷惑，這也是惟一須要一點額外工做的地方，別急，下面立刻就講到它。

(2) @ApiDoc 是咱們定義的一個註解，除非程序運行起來，不然咱們是沒辦法知道 response 裏面都包含有哪些內容，可是咱們明明有了相關的視圖類，爲了解決這個問題，咱們折衷設計了這個基於RetentionPolicy.SOURCE的註解，它不會給現有的代碼形成任何的負擔。因爲是基於 Java 源碼進行解析的，因此你不須要依賴咱們的 Jar 包，你能夠在你本身的工程任意地方添加這個簡單的類便可，固然，若是你連這個也不肯意也是不要緊的，你只須要直接添加咱們的 Jar 包便可，裏面已經爲你準備好這個類了。

@Retention(RetentionPolicy.SOURCE)
@Target({ElementType.METHOD})
public @interface ApiDoc {

    /** * result class * @return */
	Class<?> value() default Null.class;

    /** * result class */
	Class<?> result() default Null.class;

    /** * request url */
	String url() default "";

    /** * request method */
	String method() default "get";

    final class Null{

    }
}

複製代碼

若是你用的是咱們深度支持的 MVC 框架，那麼你只須要寫好返回的視圖模型就能夠了。

(3) 你能夠在項目的目錄下找到有兩個，一個是all結尾的，裏面包含了第三方的依賴包，一個是min結尾的，不含第三方的依賴包。

命令行模式:

下載all包，而後在和這個jar包相同目錄下建立名稱是docs.config的配置文件，裏面能夠配置這幾個參數：

projectPath = 工程目錄（必須）
docsPath = 文檔輸出目錄（非必須，默認是${projectPath}/apidocs）
codeTplPath = 代碼模版目錄 (非必須，若是你須要自定義生成的代碼纔會用到。)
mvcFramework = [spring, play, jfinal, generic](非必須，代碼內部有判斷，若是出現誤判的狀況，能夠經過這個強制指定)

複製代碼

配置好以後，運行該jar包就能夠了。

java -jar ***-all.jar
複製代碼

代碼模式

若是想作一些持續集成的話，代碼模式仍是比較方便的，根據你的須要能夠選擇all包或者min包，相關第三方依賴以下：

compile 'com.google.code.gson:gson:2.8.0'
compile 'com.github.javaparser:javaparser-core:3.3.0'
複製代碼

只須要調用下面一句代碼便可：

Docs.buildHtmlDocs(DocsConfig config);
複製代碼

(4) 自定義輸出 Java 和 IOS 代碼：

你能夠把工程裏面相關的代碼模板文件拷貝出來，而後在配置參數聲明好該路徑便可，具體的模板文件以下：

(5) 更多的用法和不一樣的框架能夠參考咱們的示例代碼。

注意的地方

(1) 返回視圖類不支持循環引用，會致使 stackoverflow。

class UserVO{
    BookVO book;
}

class BookKVO{
    UserVO user;
}
複製代碼

(2) JFinal 路由配置必須在 configRoute 方法體裏，不然會解析失敗。

@Override
    public void configRoute(Routes me) {
        me.add("/api/v1/user", UserController.class);
        me.add("/api/v1/book", BookController.class);
        me.add(new AmdinRoutes());
    }
複製代碼

支持和反饋

因爲每一個人寫代碼的習慣可能都不同，雖然已經儘量考慮到了多種不一樣的狀況，但因爲做者本人的認知和精力有限，不免會疏忽或者自己就存在有 bug 的狀況，若是你在使用的過程當中有碰到困難或者疑問，歡迎提issue或者加扣扣羣進行反饋：70948803。

若是你以爲這個項目對你有用，請猛戳 star。你的支持是我前進的動力！

技術交流羣：70948803，大部分時間羣裏都是安靜的，只交流技術相關，不多發言，不歡迎廣告噴子。