大家都晓得 Swagger 是一个罕用的 Spring Boot 接口文档生成工具，然而咱们明天再介绍另外一个无需额定注解的 Spring Boot API 文档生成神器，十分不便好用！
JApiDocs 是一个无需额定注解、开箱即用的 Spring Boot 接口文档生成工具。
编写和保护 API 文档这个事件，对于后端程序员来说，是一件宜人但又不得不做的事件，咱们都不喜爱写文档，但除非我的项目前后端代码都是本人写的，否则 API 文档将是前后端合作中一个不可或缺的沟通界面。既然不可避免，那就想方法弄个轮子吧。人生苦短，必须偷懒。
无图无假相，生成文档的成果如下：

相比 Swagger 要写一堆注解，Spring RestDocs 须要写测试用例，能力生成 API 文档。JApiDocs 具备无痛集成的特点，你只需花几分钟就能晓得它怎么用了。

入门

反对 JDK：1.8+

疾速开始

第一步：增加依赖

maven:

<dependency>
  <groupId>io.github.yedaxia</groupId>
  <artifactId>japidocs</artifactId>
  <version>1.4.4</version>
</dependency>

gradle:

compile 'io.github.yedaxia:japidocs:1.4.4'

第二步：配置参数

你能够在任意一个 main 入口运行上面的代码：

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

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

编码标准

JApiDocs 是通过解析 Java 源码来实现的，要使得 JApiDocs 正确工作，须要你在我的项目中的 Controller 书写遵循肯定的编码标准。

你能够联合源码中 SpringDemo 这个模块来对照了解。

1. 增加必要的代码正文

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

/**
 * 用户接口
 */
@RequestMapping("/api/user/")
@RestController
public class UserController {


    /**
     * 用户列表
     * @param listForm
     */
    @RequestMapping(path = "list", method = {RequestMethod.GET,  RequestMethod.POST}  )
    public ApiResult<PageResult<UserVO>> list(UserListForm listForm){return null;}

    /**
     * 保留用户
     * @param userForm
     */
    @PostMapping(path = "save")
    public ApiResult<UserVO> saveUser(@RequestBody UserForm userForm){return null;}

    /**
     * 删除用户
     * @param userId 用户 ID
     */
    @PostMapping("delete")
    public ApiResult deleteUser(@RequestParam Long userId){return null;}
}

如果提交的表单是 application/x-www-form-urlencoded 类型的 key/value 格局，你能够在 SpringBoot 端通过在 @param 参数后增加字段解释或者在相干的 JavaBean 对象外面增加解释：

// 间接在 java 的 @param 注解中
@param userId 用户 ID

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

这种格局对于到文档中的参数形容将是表格的模式：

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

{
  "id": "long // 用户 ID",
  "name": "string // 用户名",
  "phone": "long // 电话",
  "avatar": "string // 头像",
  "gender": "byte // 性别"
}

2. 接口申明返回对象

咱们晓得，如果 Controller 申明了@RestController，SpringBoot 会把返回的对象间接序列成 Json 数据格式返回给前端。
JApiDocs 也利用了这一个性来解析接口返回的后果，但因为 JApiDocs 是动态解析源码的，因而你要明确指出返回对象的类型信息，JApiDocs 反对继承、泛型、循环嵌套等简单的类解析。

比方下面的 saveUser 接口：

 /**
 * 保留用户
 * @param userForm
 */
@PostMapping(path = "save")
public ApiResult<UserVO> saveUser(@RequestBody UserForm userForm){return null;}

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

{
  "code": "int",
  "errMsg": "string",
  "data": {
    "userId": "string // 用户 id",
    "userName": "string // 用户名",
    "friends": [
      {
        "userId": "string // 用户 id",
        "userName": "string // 用户名"
      }
    ],
    "readBooks": [
      {
        "bookId": "long // 图书 id",
        "bookName": "string // 图书名称"
      }
    ],
    "isFollow": "boolean // 是否关注"
  }
}

如果你不是通过返回对象的模式，你也能够通过 JApiDocs 提供的 @ApiDoc 注解来申明返回类型，你能够参考 @ApiDoc 章节的相干配置内容。

3. 接口对象在源码中

咱们晓得，通过编译后的 class 字节码中是没有正文信息的。所以为了让 JApiDcos 能更好地工作，你的表单 Bean 类和返回类最好在源码中，否则生成的文档将会缺失阐明信息。
在 1.4.2 版本中，JApiDocs 在找不到源码的状况下（依赖类在 jar 包中）也会通过尝试反射的形式来解析字段信息，但这样就没有阐明信息了。

后续会打算通过关联源码的模式来解决这个问题。

高级配置

@ApiDoc

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

如果你不心愿把所有的接口都导出，你能够把 autoGenerate 设置敞开，在相干 Controller 类或者接口办法上通过增加 @ApiDoc 来确定哪些接口须要导出。

当 @ApiDoc 申明在接口办法上的时候，它还领有一些更灵便的设置，上面咱们来看一下：

• result: 这个能够间接申明返回的对象类型，如果你申明了，将会笼罩 SpringBoot 的返回对象
• stringResult：返回字符串，在返回后果比较简单，而不想创立一个专门的返回类，则能够思考应用这个属性。
• url: 申请 URL，扩大字段，用于反对非 SpringBoot 我的项目
• method: 申请办法，扩大字段，用于反对非 SpringBoot 我的项目

例子：

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

stringResult 实例，在文档中将会主动格式化 json 字符串：

@ApiDoc(stringResult = "{code: 0, data:'success'}")
@GetMapping(value = "custom-json")
public Map customJsonResult(){}

@Ignore

疏忽 Controller

你只须要在 Controller 类上增加该注解即可，这样，整个 Controller 的接口都会被疏忽掉：

@Ignore
public class UserController {}

疏忽接口

不难理解，就是在接口办法中增加 @Ignore 注解：

@Ignore
@PostMapping("save")
public ApiResult saveUser(){return null;}

疏忽字段

如果你不想导出对象外面的某个字段，能够给这个字段加上 @Ignore 注解，这样 JApiDocs 导出文档的时候就会主动疏忽掉了：

例子:

public class UserForm{
   @Ignore
   private Byte gender; // 性别
}

@description

在 Controller 类上应用

在类上应用 @description，将会作为该 Controller 在文档上的导航题目，而不会应用下面的正文内容。

/**
 * 演示一些比拟非凡的申明办法
 *
 * @description 管理员接口
 * @author yeguozhong yedaxia.github.com
 */
@Controller
public class AdminController {

在接口办法上应用

在办法中应用，则能够在接口办法上面增加一行阐明：

/**
  * 用户列表
  * @description 这是一行阐明
  * @param listForm
  * @author yedaxia
  */
  @RequestMapping(path = "list", method = {RequestMethod.GET,  RequestMethod.POST}  )
  public ApiResult<PageResult<UserVO>> list(UserListForm listForm){}

导出更多格局

导出 markdown

config.addPlugin(new MarkdownDocPlugin());

导出 pdf 或者 word

你能够通过 pandoc 把 markdown 格局转成 pdf 或者 word 格局。

自定义代码模板

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

第一步：定义代码模板

把源码中 library 我的项目 resources 目录下的代码模板拷贝一份，其中，IOS_示意 Object-C 代码模板，JAVA_结尾示意 Java 代码，
模板中相似 ${CLASS_NAME} 的符号是替换变量，具体含意你能够联合生成的代码进行了解，而后依照你想要的代码模板进行批改即可。

第二步：抉择新的模板

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

docsConfig.setResourcePath("模板门路");

增加更多功能

JApiDocs 提供了插件接口，你能够通过插件接口来实现更多丰盛的性能，上面介绍如何增加插件：

第一步：实现 IPluginSupport 接口

public class CustomPlugin implements IPluginSupport{
    
    @Override
    public void execute(List<ControllerNode> controllerNodeList){// 实现你本人的性能需要}
}

第二步：增加插件

 config.addPlugin(new CustomPlugin());

常见问题

1、如何排查谬误？

敞开主动生成config.setAutoGenerate(Boolean.FALSE)，应用@ApiDoc 来一个个接口导出排查问题。

2、多模块找不到相干类源码？

如果源码门路没有全副辨认进去，能够通过 config.addJavaSrcPath 来增加模块的源码门路，留神要增加到 src/main/java 这一级。

晓得的越多不晓得的更多