優於 swagger 的 java markdown 文檔生成框架-01-入門使用
阿新 • • 發佈：2019-03-19
ons dem plugins lin 別人 工具 全面 java 註解 -c 設計初衷
節約時間
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 docMarkdown 的生成
參考 03-自定義生成文件過濾器
效果參見 idoc-test-全部文檔.md
進一步學習
00-項目概覽
01-設計初衷
02-插件的參數配置
03-自定義生成文件過濾器
04-字段類型別名支持
開源地址
idoc
優於 swagger 的 java markdown 文檔生成框架-01-入門使用