極簡Java文檔工具smalldoc-2.3.1發佈

• 項目地址：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