JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具。

编写和维护API文档这个事情，对于后端程序员来说，是一件恼人但又不得不做的事情，我们都不喜欢写文档，但除非项目前后端代码都是自己写的，否则API文档将是前后端协作中一个不可或缺的沟通界面。

既然不可避免，那就想办法弄个轮子吧。人生苦短，必须偷懒。

无图无真相，生成文档的效果如下：

功能特性

1、代码即文档

JApiDocs是通过直接解析SpringBoot的源码语法来工作的，所以只要Controller的语法符合一定的代码规范，有合理的注释，就可以直接导出文档。

2、支持导出HTML

便捷的导航和接口查看界面；可本地预览，或者部署到HTTP服务器。推荐部署到服务器，方便前后端展开协作。

3、同步导出客户端Model代码

支持导出Android端的 Java 和iOS端的 Object C Model代码，减少前端程序员的重复编码工作。

4、更多特性

支持接口搜索；支持不同版本和英文文档；自定义扩展等。

简洁的文档

再好用的东西，如果没有文档说明，别人也无从入手。为了让大家尽快上手，JApiDocs准备了一份极简的文档说明，确保你在几分钟就能用上JApiDocs。

花5分钟不到就能认识一个提高工作效率的工具，让你把更多的时间花在更加有价值的事情上，你确认不看一下吗？

仓库地址：https://github.com/YeDaxia/JApiDocs

 中文文档：https://japidocs.agilestudio.cn/#/zh-cn/

支持接口搜索；支持不同版本和英文文档；自定义扩展等。

入门

支持JDK：1.8+

快速开始

第一步：添加依赖

maven:

1. <dependency>
2. <groupId>io.github.yedaxia</groupId>
3. <artifactId>japidocs</artifactId>
4. <version>1.3</version>
5. </dependency>

gradle:

1. compile 'io.github.yedaxia:japidocs:1.3'

第二步：配置参数

你可以在任意一个main入口运行下面的代码：

1. DocsConfig config = new DocsConfig();
2. config.setProjectPath("your springboot project path"); // 项目根目录
3. config.setProjectName("ProjectName"); // 项目名称
4. config.setApiVersion("V1.0"); // 声明该API的版本
5. config.setDocsPath("your api docs path"); // 生成API 文档所在目录
6. config.setAutoGenerate(Boolean.TRUE); // 配置自动生成
7. Docs.buildHtmlDocs(config); // 执行生成文档

如果没有意外，执行完上面的代码后，你就可以在配置的目录中看到生成的文档了。

编码规范

JApiDocs是通过解析Java源码来实现的，要使得JApiDocs正确工作，需要你在项目中的 Controller书写遵循一定的编码规范。

你可以结合源码中 SpringDemo 这个模块来对照理解。

1. 添加必要的代码注释

其中类注释会对应到一级接口分组，你也可以通过 @description来指定分组名称；JApiDocs 会通过 @param 来寻找接口参数和进一步解析参数的内容。

1. /**
2. * 用户接口
3. */
4. @RequestMapping("/api/user/")
5. @RestController
6. public class UserController {
8. /**
9. * 用户列表
10. * @param listForm
11. */
12. @RequestMapping(path = "list", method = {RequestMethod.GET, RequestMethod.POST} )
13. public ApiResult<PageResult<UserVO>> list(UserListForm listForm){
14. return null;
15. }
17. /**
18. * 保存用户
19. * @param userForm
20. */
21. @PostMapping(path = "save")
22. public ApiResult<UserVO> saveUser(@RequestBody UserForm userForm){
23. return null;
24. }
26. /**
27. * 删除用户
28. * @param userId 用户ID
29. */
30. @PostMapping("delete")
31. public ApiResult deleteUser(@RequestParam Long userId){
32. return null;
33. }
34. }

如果提交的表单是 application/x-www-form-urlencoded 类型的 key/value格式，你可以在 SpringBoot 端通过在 @param 参数后添加字段解释或者在相关的JavaBean对象里面添加解释：

1. // 直接在java的 @param 注解中
2. @param userId 用户ID

1. // 在FormBean对象中
2. public class UserListForm extends PageForm{
3. private Integer status; //用户状态
4. private String name; //用户名
5. }

这种格式对于到文档中的参数描述将是表格的形式：

如果提交的表单是 application/json 类型的 json数据格式，对应 SpringBoot 中的 @RequestBody 注解，在文档中则是 json 格式显示：

1. {
2. "id": "long //用户ID",
3. "name": "string //用户名",
4. "phone": "long //电话",
5. "avatar": "string //头像",
6. "gender": "byte //性别"
7. }

2. 接口声明返回对象

我们知道，如果 Controller声明了 @RestController，SpringBoot会把返回的对象直接序列成Json数据格式返回给前端。JApiDocs也利用了这一特性来解析接口返回的结果，但由于JApiDocs是静态解析源码的，因此你要明确指出返回对象的类型信息，JApiDocs支持继承、泛型、循环嵌套等复杂的类解析。

比如上面的 saveUser接口：

1. /**
2. * 保存用户
3. * @param userForm
4. */
5. @PostMapping(path = "save")
6. public ApiResult<UserVO> saveUser(@RequestBody UserForm userForm){
7. return null;
8. }

ApiResult<UserVO>表明了该接口返回的数据结构，经过JApiDocs处理后是这样的：

1. {
2. "code": "int",
3. "errMsg": "string",
4. "data": {
5. "userId": "string //用户id",
6. "userName": "string //用户名",
7. "friends": [
8. {
9. "userId": "string //用户id",
10. "userName": "string //用户名"
11. }
12. ],
13. "readBooks": [
14. {
15. "bookId": "long //图书id",
16. "bookName": "string //图书名称"
17. }
18. ],
19. "isFollow": "boolean //是否关注"
20. }
21. }

如果你不是通过返回对象的形式，你也可以通过JApiDocs提供的 @ApiDoc注解来声明返回类型，你可以参考 @ApiDoc章节的相关配置内容。

3. 接口对象在源码中

我们知道，经过编译后的 class 字节码中是没有注释信息的，如果要通过反射字节码的方式来实现，则不可避免要引入运行时注解，这样会增加使用成本， 考虑到这一点，JApiDocs 从第二个版本之后就改成了使用解析源码的方式，而不是反射字节码的思路来实现了，但这样直接导致的缺陷就是：所有的 Form Bean (表单)对象和返回对象就必须在项目的源码中，否则就无法解析了，如果你们项目的JavaBean对象是通过jar包的形式提供的， 那很遗憾，JApiDocs将无法支持。

高级配置

@ApiDoc

JApiDocs 默认只导出声明了 @ApiDoc的接口，我们前面通过设置 config.setAutoGenerate(Boolean.TRUE) 来解除了这个限制。

如果你不希望把所有的接口都导出，你可以把 autoGenerate设置关闭，在相关 Controller类或者接口方法上通过添加 @ApiDoc来确定哪些接口需要导出。

当 @ApiDoc声明在接口方法上的时候，它还拥有一些更灵活的设置，下面我们来看一下：

• result: 这个可以直接声明返回的对象类型，如果你声明了，将会覆盖SpringBoot的返回对象
• url: 请求URL，扩展字段，用于支持非SpringBoot项目
• method: 请求方法，扩展字段，用于支持非SpringBoot项目

例子：

1. @ApiDoc(result = AdminVO.class, url = "/api/v1/admin/login2", method = "post")

@Ignore

如果你不想导出对象里面的某个字段，可以给这个字段加上 @Ignore注解，这样JApiDocs导出文档的时候就会自动忽略掉了：

例子:

1. public class UserForm{
2. @Ignore
3. private Byte gender; //性别
4. }

自定义代码模板

JApiDocs 除了支持文档导出，目前也支持生成了 Android 和 iOS 的返回对象代码，对应 Java 和 Object-C 语言， 如果你想修改代码模板，可以通过以下的方法：

第一步：定义代码模板

把源码中 library项目 resources目录下的代码模板拷贝一份，其中， IOS_表示 Object-C 代码模板， JAVA_开头表示 Java代码， 模板中类似 ${CLASS_NAME}的符号是替换变量，具体含义你可以结合生成的代码进行理解，然后按照你想要的代码模板进行修改即可。

第二步：选择新的模板

通过 DocsConfig配置模板路径替换成新的模板：

1. docsConfig.setCodeTplPath("模板路径");

添加更多功能

JApiDocs 提供了插件接口，你可以通过插件接口来实现更多丰富的功能，下面介绍如何添加插件：

第一步：实现 IPluginSupport 接口

1. public class CustomPlugin implements IPluginSupport{
3. @Override
4. public void execute(List<ControllerNode> controllerNodeList){
5. // 实现你自己的功能需求
6. }
7. }

第二步：添加插件

1. config.addPlugin(new CustomPlugin());