java建立项目文件夹接口_Spring项目集成apidoc生成api接口文档

一、背景需求

JavaWeb/spring项目写成的api接口，需要自动生成api文档，甚至需要在线测试接口。考虑实现的方案有swagger，apidoc，spring rest docs。在之后的项目都有一一尝试，最终还是觉得apidoc的方式比较合适，虽然有一些问题(针对在线测试方面)，但可以进行定制修复并解决。

二、方案对比

1.现在大家普遍使用的是swagger结合springmvc来生成api接口文档，对比apidoc，swagger有一个明显的劣势，便是返回的响应，无法生成文档描述，即无法描述响应体的数据结构，这对前后端对接，或者是与移动端/其他端对接来说，需要耗费更多的交流成本，沟通成本，即不可能每个接口都通过实际调用后，看返回实体获悉响应参数。针对后端改动响应体这种情况，又会导致新的问题存在。

2.spring rest docs，这是spring体系里提供的一种接口生成框架，基于mockmvc编写单元测试，单元测试通过即可生成可供阅读的接口文档。这种生成方式需要编写详细的测试单元，并且稍微一点出错便导致编译不通过，对于程序的严谨有一定帮助，但又牺牲一些时间，并且最终生成的文档是基于测试用例数据，没有类似swagger和apidoc的在线测试功能。

3.apidoc，通过注释，生成接口文档，不像swagger和spring rest docs嵌入在代码中，仅仅是通过注释而已。缺点是在线测试功能有些问题，不支持文件表单，但这些缺陷都是可以弥补的，可通过再编程，重新定制源码实现，基于handlebars