极简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