目錄
- 項目地址:https://github.com/liuhuagui/smalldoc
- 快速使用:https://github.com/liuhuagui/smalldoc#user-content-%E4%BD%BF%E7%94%A8
很高興 smalldoc 能夠幫助 Java Web 開發人員解決文檔書寫的麻煩,將你們從 swagger 的繁瑣註解中解救出來,也感謝使用者提出的 issues 幫助 smalldoc 變得更完善更便捷。
smalldoc-2.3.1根據 issues更新如下:
修復並優化 source-paths 與 packages 配置
source-paths 默認已經給出當前項目源碼路徑(即,引入該smalldoc依賴的項目的源碼路徑 —— System.getProperty("user.dir")
, 2.3.1
修復了不配置路徑的空指針錯誤。
- 只有當你需要第三方jar包源碼
- 或者你的項目是多模塊項目需要引入其他模塊的源碼,纔有必要配置 source-paths。
packages 配置Controller類
所在的包,會自動遞歸它們子包。如果沒有指定,默認爲/
,將掃描源碼路徑下所有包,建議給出指定包名,提升解析速度。
遞歸解析返回參數
無論你的返回對象有幾層,都可以顯示在返回參數表格中,如下圖
支持列表或分頁接口返回值中List元素結構的解析
修復*Mapping註解
解析異常。
java.lang.ClassCastException: java.lang.Boolean cannot be cast to [Lcom.sun.javadoc.AnnotationValue;
採用註釋的方式支持參數是否必須,支持List,Set,數組,和實體參數
- 普通參數 ,有且僅在註釋後添加
@*
表示必須,否則爲可選參數。包括基本類型,基本類型的包裝類型,字符串,以及它們的數組,List,Set,同時還有一些庫類型
—— 例如 File , MultipartFile - 實體參數 ,實體類中的所有字段都可能作爲參數被傳遞,而且每個接口所需要傳遞字段的要求不盡相同,所以我們不可能在 DTO實體 中做標記,這樣不僅有代碼侵入性,同時也不能滿足接口傳參的多樣性。
實體參數的註釋,可以使用@{f1[*],[f2[*],...]}
這種形式來寫,要麼代替整個註釋,要麼放在註釋最後。- 其中
f
表示實體類的某個字段名,通過它 ,smalldoc 可以去你的實體類源碼中搜尋參數的註釋。 - 字段名後添加
*
表示必須,否則爲可選參數。 - 如果實體類中的字段沒有出現在
@{}
內,該字段將不會作爲參數。 - 如果在
@
之前還有其它註釋內容,將被忽略。 - 如果你的參數是實體參數,註釋結尾卻不包含該形式,那麼將會打印警告日誌,幫你預先定位該問題。
- 其中
示例如下。
優化參數名展示
優化過後的參數名支持複雜數據結構,比如關聯對象,關聯集合,Set,List或數組,可直接作爲實際參數名進行接口調用。
示例代碼
/**
* 測試接口
* @param file 文件
* @param bb saddas
* @param cc CCCC
* @param pp h哈哈是@*
* @param cca 擦擦擦黑@{authorId*}
* @param content 內容@*
* @param oaCopyArray @{authorId*,originalArticleId,categoryId*,paragraph.content}
* @param oaCopy @{authorId*,originalArticleId,categoryId*,paragraph.content}
* @return data-草稿ID
*/
@RequestMapping("test_path/action2")
public Result<Long> test(MultipartFile file, Long[] bb , Long cc, List<String> pp, String content, List<OriginalArticleCopy> cca, OriginalArticleCopy[] oaCopyArray, OriginalArticleCopy oaCopy, HttpServletRequest request) {
return null;
}
文檔顯示
增加大量斷言
如果你的註釋不規範,無法生成合理文檔,smalldoc 將打印警告或直接提示異常
支持離線文檔
最初的 smalldoc-antd-react-ui 【https://github.com/liuhuagui/smalldoc-antd-react-ui】,採用 React+Fetch
的形式獲得文檔結構,新版本改用
React+模板引擎
寫法,使支持離線文檔,你只需要在瀏覽器中打開文檔UI界面,然後 Ctrl+S
保存離線文件。
下個版本將會更新
- 優化父類字段存儲方式,減少請求數據
- 爲滿足微服務多包接口的便捷性,增加包名導航(可選擇關閉或開啓,默認關閉)
- 希望能夠給Java開發者帶來更多幫助,更多更新期待你們的 issue