收集文档的小项目

[liuanxin]

基于 spring mvc 新写了一个用来收集项目文档的小项目: https://github.com/liuanxin/api-document

长时间维护过项目的人应该都能体会, 如果单独编写文档的话, 随着项目周期的推进, 赶项目等各种需要临时修改代码的片段, 最后很容易出现一个结果: 接口文档和真实代码之间的差距会越来越远. 所以就有了像 springfox(swagger) 这一类跟随项目的文档工具.

也是用了一段时间的 springfox, 其有些小细节总是觉得不怎么好, 比如: 如果返回的实体里面有一个 Map<String, XXX> xxxMap 这样的字段, 在 springfox 的文档中, 这个 xxxMap 是没有说明的, 只有 inline_model 这么一个提示, 再有就是它的返回示例和字段说明, 需要在不同的选项卡中切换来查看也总是有点别扭(这里是指跟随项目的 swagger-ui 展示出来的结果).

项目的原理是基于 spring mvc 内部的 RequestMappingHandlerMapping 来完成的, 反射方法和类的一些信息, 页面上用了之前在写文档的时候用到的 ox-twbs(个人不怎么习惯 md)

收集出来的接口差不多是像下面这样 https://raw.githubusercontent.com/liuanxin/image/master/api.png

如果不习惯注释跟随在返回示例中, 全局设定一个参数即可, 最后会像这样 https://raw.githubusercontent.com/liuanxin/image/master/api2.png

建议注释跟文档在一起, 这样当返回字段多的时候, 不需要分屏.

如果参数和返回结果里面有 enum, 会自动获取其 getCode 和 getValue 放到文档中(通常前者用来参数传递, 后者用来中文显示), 如果没有会收集 name() 成列表并返回.

硬伤也有: 相比 springfox, 没有即时调试的功能(定位只是用来收集文档), 有一个 mock url 可以查看不带注释的 json 结果. 另外也不支持 ResponseEntity 这一类没有 <无参构造> 的返回

[WittBulter]

good ！
（如果手动写文档不妨试试这个工具 https://github.com/DhyanaChina/simpler-paper ）

[liuanxin]

@WittBulter 以前就是手动写文档的, 用的 emacs + org mode(个人并不是很喜欢 markdown), 手写文档一开始还能保持同步, 一旦项目上线后两者的差异就会越来越远