如何快速实现spring boot技术栈api文档的生成

做为开发，写接口文档一直是一个很头痛的问题，尤为在先后端分离大量盛行的当下，后端必需要为前端同事提供明确的入参出参文档，不然整个对接工做没法顺利进行，先后端的相爱相杀的大戏时常上演。笔者刚工做的那些年，swagger都尚未正式发布，对接前端和app端的文档全靠手写markdown完成。写接口文档的时间经常感jio比写代码耗费的时间还长。随着技术的进步和众多开源人的努力，近几年针对java开发的文档生成工具愈来愈多。新入行的开发人员不再用去体会过去的那些辛酸历程。在java文档生成的这个领域，swagger一直是一只领头羊。可能占据着90%的市场， 除此还有像 Spring REST Doc这些有名的工具也被大量的使用，可是这些工具在笔者看来使用比较蛮烦，侵入性高。今天笔者要给你们介绍和推荐一款本人开源的文档工具smart-doc，也会介绍如何使用这个工具来生成本身的文档。

1、当前市面上文档工具存在的问题

下面来列举当前市场上主流文档工具的问题：

• 侵入性强，须要编写大量注解，表明工具如：swagger，还有一些公司自研的文档工具
• 强依赖性，若是项目不想使用该工具，业务代码没法编译经过。
• 代码解析能力弱，使用文档不齐全，主要表明为国内众多开源的相关工具。
• 众多基于注释分析的工具没法解析jar包里面的注释(sources jar包)，须要人工配置源码路径，没法知足DevOps构建场景。
• 没法支持多模块复杂项目代码分析。

2、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

3、smar-doc的不足

smart-doc并不是是完美的，仍然有不少不足。

• 界面支持不完善，没有发送请求的页面，没法知足小团队自测。
• 一些使用场景支持不完善，存在一些bug。
• 暂不支持其余框架文档的生成，如：dubbo等。
• 开源团队人员少，功能实现慢。
• 当前缺少gradle插件支持。

4、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>
	</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，请记得为咱们项目点赞，您的支持是咱们一直开源的动力！！！