Spring Boot集成smart-doc生成api文档
mart-doc是一个java restful api文档生成工具,smart-doc颠覆了传统类似swagger这种大量采用注解侵入来生成文档的实现方法。smart-doc完全基于接口源码分析来生成接口文档,完全做到零注解侵入,你只需要按照java标准注释的写,smart-doc就能帮你生成一个简易明了的markdown或是一个像GitBook样式的静态html文档。下面将介绍如何在Spring
作为开发,写接口文档一直是一个很头痛的问题,尤其在前后端分离大量盛行的当下,后端必须要为前端同事提供明确的入参出参文档,否则整个对接工作无法顺利进行,前后端的相爱相杀的大戏时常上演。笔者刚工作的那些年,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-gradle-plugin
插件,项目仅仅依赖插件,剔除插件无修改项目不报任何编译错误。smart-doc
在国内经过上百家企业的使用,做了很多场景的分析,解析能力很强。smart-doc
的maven
和gradle
插件自动分析项目依赖,自动完成对自发布jar
包和第三方jar
包源码的加载,不需要指定任何源码路径。smart-doc
的maven
和gradle
能够自动识别项目依赖,多模块maven
和gradle
项目都不是问题。smart-doc
文档维护比较完善。
三、smar-doc的不足
smart-doc
并非是完美的,仍然有很多不足。
- 不支持
GRPC
- 一些使用场景支持不完善,存在一些bug。
- 开源团队人员少,功能实现慢。
四、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>[最新版本]</version>
<configuration>
<!--指定生成文档使用的配置文件-->
<configFile>./src/main/resources/smart-doc.json</configFile>
</configuration>
<executions>
<execution>
<!--不需要在编译项目时自动生成文档可注释phase-->
<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
配置简单又不会影响到项目。想了解更多详细配置请参考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
不断完善的开发者,我们也非常欢迎加入。如果您喜欢smart-doc
,请记得为我们项目点赞,您的支持是我们一直开源的动力!!!
更多推荐
所有评论(0)