如何快速实现springboot技术栈api文档的生成
一、当前市面文档工具存在的问题
下面来列举当前市场上主流文档工具的问题：
- 侵入性强，需要编写大量注解，代表工具如：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不断完善的开发者，我们也非常欢迎加入。
以上是 如何快速实现springboot技术栈api文档的生成 的全部内容， 来源链接： utcz.com/z/513532.html
