如何快速实现spring boot技术栈api文档的生成
作为开发，写接口文档一直是一个很头痛的问题，尤其在前后端分离大量盛行的当下，后端必须要为前端同事提供明确的入参出参文档，否则整个对接工作无法顺利进行，前后端的相爱相杀的大戏时常上演。笔者刚工作的那些年，swagger都还没有正式发布，对接前端和app端的文档全靠手写markdown完成。写接口文档的时间常常感jio比写代码耗费的时间还长。随着技术的进步和众多开源人的努力，近几年针对java开发的文档生成工具原来越多。新入行的开发人员再也不用去体会过去的那些辛酸的历程。在java文档生成的这个领域，swagger一直是一只领头羊。可能占据着90%的市场， 除此还有像 Spring REST Doc这些有名的工具也被大量的使用，但是这些工具在笔者看来使用比较蛮烦，侵入性高。今天笔者要给大家介绍和推荐一款本人开源的文档工具smart-doc，也会介绍如何使用这个工具来生成自己的文档。 一、当前市面文档工具存在的问题 下面来列举当前市场上主流文档工具的问题： 侵入性强，需要编写大量注解，代表工具如：swagger，还有一些公司自研的文档工具 强依赖性，如果项目不想使用该工具，业务代码无法编译通过。 代码解析能力弱，使用文档不齐全，主要代码为国内众多开源的相关工具。 众多基于注释分析工具无法分析jar包里面的注释(sources jar包)，需要人工配置源码路径，无法满足devops构建场景。 无法支持多模块复杂项目代码分析。 二、smart-doc如何解决上述问题 通过分析源码注释自动生成API文档，不用编写任何注解，秉承注释即文档的原则，并且提供注释强制检查。 smart-doc开发了smart-doc-maven-plugin插件，项目仅仅依赖插件，剔除插件无修改项目不报任何编译错误。 smart-doc在国内经过上百家企业的使用，做了很多场景的分析，解析能力很强。 smart-doc-maven-plugin插件自动分析项目依赖完成对自发布jar包和第三方jar包源码的加载，不需要指定任何源码路径。 smart-doc-maven-plugin能够识别项目依赖，多模块maven项目不是问题。 smart-doc文档维护比较完善，码云上的wiki有16个页面介绍各种使用方式。 关于smart-doc 三、smar-doc的不足 smart-doc并非是完美的，仍然有很多不足。 界面支持不完善，没有发送请求的页面，无法满足小团队自测。 一些使用场景支持不完善，存在一些bug。 暂不支持其他框架文档的生成，如：dubbo等。 开源团队人员少，功能实现慢。 当前缺乏gradle插件支持。 四、spring boot集成smart-doc生成文档。 上面说了关于一起其它工具的问题，也介绍了smart-doc的优缺点，下面进入正题，如何快速使用smart-doc生成文档。 4.1 添加插件 在spring boot项目pom中添加smart-doc的maven插件 <plugin> <groupId>com.github.shalousun</groupId> <artifactId>smart-doc-maven-plugin</artifactId> <version>1.0.2</version> <configuration> <!--指定生成文档的使用的配置文件--> <configFile>./src/main/resources/smart-doc.json</configFile> <!--指定项目名称--> <projectName>测试</projectName> </configuration> <executions> <execution> <phase>compile</phase> <goals> <goal>html</goal> </goals> </execution> </executions> </plugin> 4.2 添加smart-doc.json配置文件 在4.1的代码片段中看到需要给插件指定一个生成文档的配置文件smart-doc.json。文件内容如下： { "serverUrl": "http://127.0.0.1",//服务器地址 "isStrict": false,//是否用严格模式，严格模式强制检查注释 "allInOne": true,//所有接口文档合并生成到一个文档 "outPath": "src/main/resources/static/doc",//文档的输出路径 "projectName": "smart-doc"//指定项目名称，用于显示在文档中 } 上面的几行配置中，实际上只有outPath值必须要填的，其他都是非必须。想了解更多详细配置请参考smart-doc插件使用 4.3 编写controller接口 @RestController @RequestMapping("/user") public class UserController { /** * 添加用户 * @param user * @return */ @PostMapping("/add") public User addUser(@RequestBody User user){ return user; } } 实体类： public class User { /** * 用户名 */ private String userName; /** * 昵称 */ private String nickName; /** * 用户地址 */ private String userAddress; /** * 用户年龄 */ private int userAge; /** * 手机号 */ private String phone; /** * 创建时间 */ private Long createTime; /** * ipv6 */ private String ipv6; /** * 固定电话 */ private String telephone; //省略get set } 4.4 运行插件生成文档 效果见4.5 4.5 用户信息操作接口 添加用户 URL:http://localhost:8080/user/add Type:POST Content-Type:application/json; charset=utf-8 Request-parameters: Parameter Type Description Required Since userName string 用户名 false - nickName string 昵称 false - userAddress string 用户地址 false - userAge int 用户年龄 false - phone string 手机号 false - createTime number 创建时间 false - ipv6 string ipv6 false - telephone string 固定电话 false - Request-example: { "userName":"鹏飞.贺", "nickName":"raymond.gutkowski", "userAddress":"Apt. 819 萧旁7699号， 章丘， 滇 852063", "userAge":41, "phone":"15018373016", "createTime":1569934393095, "ipv6":"9eb3:fada:ffd2:912e:6225:1062:a2d7:718f", "telephone":"15018373016" } Response-fields: Field Type Description Since userName string 用户名 - nickName string 昵称 - userAddress string 用户地址 - userAge int 用户年龄 - phone string 手机号 - createTime number 创建时间 - ipv6 string ipv6 - telephone string 固定电话 - Response-example: { "userName":"鹏飞.贺", "nickName":"raymond.gutkowski", "userAddress":"Apt. 819 萧旁7699号， 章丘， 滇 852063", "userAge":41, "phone":"15018373016", "createTime":1569934393095, "ipv6":"9eb3:fada:ffd2:912e:6225:1062:a2d7:718f", "telephone":"15018373016" } 总结 当前最新的smart-doc结合插件后，已经做到了非常易于使用，只需要引入插件和根据自己需求填充相关的配置即可，非常的轻量级。将smart-doc推荐给大家是为了帮助更多的同行能够快速的生成api文档，也是给一些正在自研的同行提供一些实现思路。想要参考贡献帮助smart-doc不断完善的开发者，我们也非常欢迎加入。
