如何快速实现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个页面介绍各种使用方式。
三、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不断完善的开发者,我们也非常欢迎加入。
低调大师中文资讯倾力打造互联网数据资讯、行业资源、电子商务、移动互联网、网络营销平台。
持续更新报道IT业界、互联网、市场资讯、驱动更新,是最及时权威的产业资讯及硬件资讯报道平台。
转载内容版权归作者及来源网站所有,本站原创内容转载请注明来源。
- 上一篇
疫情期,APP 崩了怎么办?阿里工程师公开高可用架构笔记
阿里妹导读: 在这场抗击新型冠状肺炎的战役中,普通人能做些什么呢?可能「宅」是现在大多数人能作出的重要贡献之一。在这些深「宅」时光里,用手机或电脑打打游戏、追追剧成了很多人暂时忘掉现实的「良药」。可是!正要上分的游戏突然崩了,正演到关键的剧情突然挂掉,最近“某某 app 崩了”带着广大网友都能领悟的痛频上热搜。网友纷纷呼唤程序员小哥哥快上班,其实疫情期间线上流量激增,很多线上应用都面临着巨大挑战……要解决高流量和突发流量这种业务冲击下,线上应用频繁崩溃的问题,首先需要审视企业目前 IT 架构是否能支撑未来的业务发展 阿里巴巴在多年 双11 高并发,高可用和高客户体验要求背景下积累了相应的技术体系,并赋能罗辑思维等客户,帮助他们落地全链路压测。本文整理自高用户、突发高流量场景下的真实案例,公布阿里在高可用架构建设过程中的实践笔记,期待帮助更多企业从容应对接下来的高流量场景。 你的应用为什么崩了? 非常复杂的服务端 在我们的日常生活中因为 app 侧相对稳定,“崩”一般发生在看不见摸不着的“服务端”(或者叫云端),而这个服务端有多复杂? 以一个较为成熟的云上架构为例,光是阿里云中构建一个在...
- 下一篇
【Vue_01】基础知识
一、Vue 介绍 1. 作者介绍 2. Vue 简介 ① Vue (读音 /vjuː/,类似于 view) 是一套用于构建用户界面的渐进式框架。 ② Vue 的核心库只关注视图层,不仅易于上手,还便于与第三方库或既有项目整合。另一方面,当与现代化的工具链以及各种支持类库结合使用时,Vue 也完全能够为复杂的单页应用提供驱动。 ③ Vue 借鉴了 Angular 的模板和双向绑定技术;借鉴了 react 的组件化和虚拟 DOM 技术。 ④ MVVM 模式是 Model-View-ViewModel 的缩写,Model 代表数据模型,定义数据操作的业务逻辑,View 代表视图层,负责将数据模型渲染到页面上,ViewModel 通过双向绑定把 View 和 Model 进行同步交互,不需要手动操作DOM 的一种设计思想 3. MVVM 介绍 M: 即Model,模型,包括数据和一些基本操作 V: 即View,视图,页面渲染结果 VM:即View-Model,模型与视图间的双向操作(无需开发人员干涉) 在MVVM之前,开发人员从后端获取需要的数据模型,然后要通过DOM操作Model渲染到Vie...
相关文章
文章评论
共有0条评论来说两句吧...
文章二维码
点击排行
推荐阅读
最新文章
- CentOS6,7,8上安装Nginx,支持https2.0的开启
- SpringBoot2整合Redis,开启缓存,提高访问速度
- CentOS7编译安装Cmake3.16.3,解决mysql等软件编译问题
- CentOS7编译安装Gcc9.2.0,解决mysql等软件编译问题
- Docker快速安装Oracle11G,搭建oracle11g学习环境
- CentOS8编译安装MySQL8.0.19
- MySQL8.0.19开启GTID主从同步CentOS8
- SpringBoot2全家桶,快速入门学习开发网站教程
- CentOS8,CentOS7,CentOS6编译安装Redis5.0.7
- CentOS7,CentOS8安装Elasticsearch6.8.6