一個給 Java 程式設計師用的 Api 文件生成工具

葉大俠發表於2017-08-11
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 程式設計師的程式設計習慣是保持一致的。

spring controller

這裡你可能會對@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 程式碼：

你可以把工程裡面相關的程式碼模板檔案拷貝出來，然後在配置引數宣告好該路徑即可，具體的模板檔案如下：

code template files

(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，大部分時間群裡都是安靜的，只交流技術相關，很少發言，不歡迎廣告噴子。

相關文章