優於 swagger 的 java markdown 文件自動生成框架-01-入門使用

葉止水發表於2019-03-18

SwaggerJava框架

設計初衷

節約時間

Java 文件一直是一個大問題。

很多專案不寫文件，即使寫文件，對於開發人員來說也是非常痛苦的。

不寫文件的缺點自不用多少，手動寫文件的缺點也顯而易見：

非常浪費時間，而且會出錯。
無法保證及時更新。程式碼已經變了，但是文件還要同步修改。需要強制人來維護這一種一致性。這很難。

為什麼不是 swagger-ui

java 的文件有幾類：

jdk 自帶的 doc 生成。這個以前實踐給別人用過，別人用 C#，看到 java 的預設文件感覺很痛苦。

就算是我們 java 開發者，也很討厭看 jdk 的文件。看著不美觀，也很累。

swagger-ui 是基於 java 註解的文件生成工具。相對而言比較優雅，也非常強大。

但是缺點也是有的。開發人員要寫 jdk 原來的註釋+註解。註解太多，導致寫起來也很痛苦，大部分開發者後來還是選擇了放棄。

那麼問題來了？我們怎麼辦才能儘可能的讓開發人員，和文件閱讀人員都樂於接受呢？

jdk 自帶的 doc 就是基於 maven 外掛的，本專案也是。

區別如下：

儘可能的保證和 Java 原生註釋一致，讓開發者很容易就可以使用。
儘可能的資訊全面，但是文件簡潔。讓文件的閱讀者享受到等同於手寫文件的體驗。
將資訊的獲取和生成區分開。方便使用者自己定義自己的輸出方式。

IDOC

i-doc 專案簡介

為 java 專案生成專案文件。

基於原生的 java 註釋，儘可能的生成簡介的文件。使用者可以自定義自己的模板，生成自己需要的文件。

特性

基於 maven 專案生成包含大部分資訊的後設資料
預設支援 markdown 簡化文件的生成，支援自定義模板
支援使用者自定義文件生成器
支援使用者自定生成文件的類過濾器

新特性

新增欄位型別別名，支援使用者自定義

快速入門

需要

jdk1.8+

maven 3.x+

maven 引入

使用 maven 引入當前 idoc 外掛。

<build>
    <plugins>
        <plugin>
            <groupId>com.github.houbb</groupId>
            <artifactId>idoc-core</artifactId>
            <version>0.1.0</version>
        </plugin>
    </plugins>
</build>
複製程式碼

測試物件的建立

為了演示文件，我們建立了一個 Address 物件。

package com.github.houbb.idoc.test.model;

/**
 * 地址
 * @author binbin.hou
 * @since 0.0.1
 */
public class Address {

    /**
     * 城市
     */
    private String country;

    /**
     * 街道
     */
    private String street;

    public String getCountry() {
        return country;
    }

    public void setCountry(String country) {
        this.country = country;
    }

    public String getStreet() {
        return street;
    }

    public void setStreet(String street) {
        this.street = street;
    }
}

複製程式碼

執行外掛

mvn com.github.houbb:idoc-core:0.0.2:idoc
複製程式碼

命令列日誌資訊

[INFO] ------------------------------------ Start generate doc
[INFO] 共計 【1】 個檔案待處理，請耐心等待。進度如下：
==================================================================================================== 100%
[INFO] Generator doc with docGenerator: com.github.houbb.idoc.core.api.generator.ConsoleDocGenerator
[INFO] ------------------------------------ 文件資訊如下：

[類名] com.github.houbb.idoc.test.model.Address
[類資訊] {"comment":"地址","docAnnotationList":[],"docFieldList":[{"comment":"城市","name":"country","type":"java.lang.String"},{"comment":"街道","name":"street","type":"java.lang.String"}],"docMethodList":[{"docMethodParameterList":[],"docMethodReturn":{"fullName":"java.lang.String","name":"String","packageName":"java.lang"},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"getCountry","seeList":[],"signature":"getCountry()"},{"docMethodParameterList":[{"docAnnotationList":[],"name":"country","type":"java.lang.String"}],"docMethodReturn":{},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"setCountry","seeList":[],"signature":"setCountry(country)"},{"docMethodParameterList":[],"docMethodReturn":{"fullName":"java.lang.String","name":"String","packageName":"java.lang"},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"getStreet","seeList":[],"signature":"getStreet()"},{"docMethodParameterList":[{"docAnnotationList":[],"name":"street","type":"java.lang.String"}],"docMethodReturn":{},"docTagList":[],"exceptionList":[],"modifiers":["public"],"name":"setStreet","seeList":[],"signature":"setStreet(street)"}],"docTagList":[{"lineNum":5,"name":"author","parameters":["binbin.hou"],"value":"binbin.hou"},{"lineNum":6,"name":"since","parameters":["0.0.1"],"value":"0.0.1"}],"fullName":"com.github.houbb.idoc.test.model.Address","modifiers":["public"],"name":"Address","packageName":"com.github.houbb.idoc.test.model"}

[INFO] ------------------------------------ Finish generate doc
複製程式碼