还在用 Swagger2 生成 Restful API 文档？来试试 Api2Doc 吧！

摘要: 本文介绍一个非常好用的自动化生成 Restful API 文档的工具——Api2Doc
它基于 SpringBoot ，原理类似于 Swagger2，但比 Swagger2 要简单好用。

本文介绍一个非常好用的自动化生成 Restful API 文档的工具——Api2Doc
它基于 SpringBoot ，原理类似于 Swagger2，但比 Swagger2 要简单好用。

此项目已经放到 github 中，需要源码的朋友请点击
这里

目录

项目背景

Api2Doc 简介

引入 Api2Doc 依赖

启用 Api2Doc 服务

给 Controller 类上添加文档注解

@Api2Doc 注解详述

@ApiComment 注解详述

@ApiError 注解详述

给文档菜单项排序

补充自定义文档

定制文档的欢迎页

定制文档的标题及图标

关闭 Api2Doc 服务

项目背景

在互联网/移动互联网软件的研发过程中，大多数研发团队前后台分工是非常明确的，
后台工程师负责服务端系统的开发，一般是提供 HTTP/HTTPS 的 Restful API 接口，
前端工程师则负责 Android、iOS、H5页面的开发，需要调用 Restful API 接口。

这就需要有一套 Restful API 文档，以帮助两方在 API 接口进行沟通，并达成一致意见。
一般情况下，编写文档的工作都会落在后台工程师身上，毕竟 API 是他们提供的嘛。

但问题是，编写 Restful API 文档是一件既繁琐、又费时、还对提高技术能力没啥帮助的苦差事，
尤其在是快速迭代、需求频繁修改的项目中，改了代码还要同步改文档，
哪点改错了或改漏了都可能产生前后端实现的不一致，导致联调时发现 BUG，
这个锅最终还是要后台工程师来背（宝宝心里苦啊...）。

因此，业界就出现了一些根据代码自动生成 Restful API 文档的开源项目，
与 Spring Boot 结合比较好的是 Swagger2，Swagger2 通过读取 Controller
代码中的注解信息，来自动生成 API 文档，可以节省大量的手工编写文档的工作量。

本项目作者之前也是用的 Swagger2，但发现 Swagger2 也有好多地方用得不爽：

第一，Swagger2 的注解非常臃肿，我们看下这段代码：

@RestController
@RequestMapping(value = "/user3")
public class UserController2Swagger2 {

@ApiOperation(value = "获取指定id用户详细信息",
notes = "根据user的id来获取用户详细信息",
httpMethod = "GET")
@ApiImplicitParams({
@ApiImplicitParam(name = "userName", value = "用户名",
paramType = "query", required = true, dataType = "String"),
@ApiImplicitParam(name = "password", value = "用户密码",
paramType = "query", required = true, dataType = "String")
})
@RequestMapping(name = "用户注册", value = "/regist",
method = RequestMethod.GET)
public UserInfo regist(@RequestParam("userName") String userName,
@RequestParam("password") String password) {
return new UserInfo();
}
}

@ApiOperation、@ApiImplicitParam 都是 Swagger2 提供的注解，用于定义 API 信息。
其实，API 方法本身就包含了很多信息，如HTTP Method、参数名、参数类型等等，
像 @ApiImplicitParam 中除了 value 属性有用外，其它都是重复描述。

第二，Swagger2 的页面排版不太友好，它是一个垂直排列的方式，不利于信息的展示。
并且看 API 详细信息还要一个个展开，中间还夹杂着测试的功能，反正作为文档是不易于阅读；
至于作为测试工具嘛...，现在专业的测试工具也有很多，测试人员好像也不选它。

第三，Swagger2 还有好多细节没做好，比如看这个图：



红框中的 API 其实对应的是同一个方法，之所以有这么多，只是因为写这个方法
时没有指定 method：

@RestController
@RequestMapping(value = "/user2")
public class UserController2Swagger2 {

@RequestMapping(value = "/do_something")
public void doSomethingRequiredLogon() {
}

// 其它方法，这里省略...
}

（当没指定 method 时，Spring Boot 会默认让这个接口支持所有的 method）

因此，考虑到与其长长久久忍受 Swagger2 的各种不爽，不如花些时间做一个
更好用的“自动化文档系统”，于是就诞生了本项目： Api2Doc 。

Api2Doc 简介

Api2Doc 专注于 Restful API 文档的自动生成，它的原理与 Swagger2 是类似的，
都是通过反射，分析 Controller 中的信息生成文档，但它要比 Swagger2 好很多。

最大的不同是： Api2Doc 比 Swagger2 要少写很多代码。

举个例子，使用 Swagger2 的代码是这样的：

@RestController
@RequestMapping(value = "/user")
public class UserController {

@ApiOperation(value = "添加用户", httpMethod = "POST",
notes = "向用户组中添加用户，可以指定用户的类型")
@ApiImplicitParams({
@ApiImplicitParam(name = "group", value = "用户组名",
paramType = "query", required = true, dataType = "String"),
@ApiImplicitParam(name = "name", value = "用户名",
paramType = "query", required = true, dataType = "String"),
@ApiImplicitParam(name = "type", value = "用户类型",
paramType = "query", required = true, dataType = "String")
})
@RequestMapping(value = "/addUser", method = RequestMethod.POST)
public User addUser(String group, String name, String type) {
return null; // TODO:  还未实现。
}
}

我们看下使用 Api2Doc 注解修饰后的代码：

@Api2Doc(id = "users")
@ApiComment(seeClass = User.class)
@RestController
@RequestMapping(value = "/api2doc/demo2")
public class UserController2 {

@ApiComment("向用户组中添加用户，可以指定用户的类型")
@RequestMapping(name = "添加用户",
value = "/user", method = RequestMethod.POST)
public User addUser(String group, String name, String type) {
return null; // TODO:  还未实现。
}

// 其它方法，这里省略...
}

看，Api2Doc 仅需要在方法上加上 @Api2Doc @ApiComment 注解等极少数代码，
但它生成的文档可一点不含糊，如下图所示：





有的朋友可能会觉得很奇怪：文档页面上的说明、示例值等内容，在代码中没有写啊，
这些是哪来的呢？

这里涉及到 Api2Doc 的核心设计理念，就是：它尽可能通过智能分析，自动收集
生成文档所需的信息，从而让用户少写代码。

说得有点抽象哈，下面我们来正面回答这个问题，请大家注意这个类上有一个注解：

@ApiComment(seeClass = User.class)

它意思是： 在 API 方法上遇到没写说明信息时，请参照 User 类中的定义的说明信息。

下面是 User 类的代码：

public class User {

@ApiComment(value = "用户id", sample = "123")
private Long id;

@ApiComment(value = "用户名", sample = "terran4j")
private String name;

@ApiComment(value = "账号密码", sample = "sdfi23skvs")
private String password;

@ApiComment(value = "用户所在的组", sample = "研发组")
private String group;

@ApiComment(value = "用户类型", sample = "admin")
private UserType type;

@ApiComment(value = "是否已删除", sample = "true")
@RestPackIgnore
private Boolean deleted;

@ApiComment(value = "创建时间\n也是注册时间。")
private Date createTime;

// 省略  getter / setter 方法。
}

大家看明白了没？ API 方法中的参数，如果与 User 类的属性同名的话，就用类
属性的 @ApiComment 说明信息自动填充。

其实这也符合实际的业务逻辑。因为在大部分项目中，有的字段会在多个实体类、
多个 API 方法中用到，完全没有必要重复编写其说明信息，只要有一个地方定义好了，
然后其它地方参照就行了。

当然，这只是 Api2Doc 比 Swagger2 好用的特性之一，还有不少比 Swagger2 好用的地方。

下面我们就来全面讲解它的用法，希望可以帮助开发者们从文档编写的苦海中解脱出来。

引入 Api2Doc 依赖

如果是 maven ，请在 pom.xml 中添加依赖，如下所示：

<dependency>
<groupId>com.github.terran4j</groupId>
<artifactId>terran4j-commons-api2doc</artifactId>
<version>${api2doc.version}</version>
</dependency>

如果是 gradle，请在 build.gradle 中添加依赖，如下所示：

compile "com.github.terran4j:terran4j-commons-api2doc:${api2doc.version}"

${api2doc.version} 最新稳定版，请参考 这里

启用 Api2Doc 服务

本教程的示例代码在 src/test/java 目录的 com.terran4j.demo.api2doc 中，
您也可以从 这里 获取到。

首先，我们需要在有 @SpringBootApplication 注解的类上，添加 @EnableApi2Doc
注解，以启用 Api2Doc 服务，如下代码所示：

package com.terran4j.demo.api2doc;

import com.terran4j.commons.api2doc.config.EnableApi2Doc;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

//  文档访问地址： http://localhost:8080/api2doc/home.html @EnableApi2Doc
@SpringBootApplication
public class Api2DocDemoApp {

public static void main(String[] args) {
SpringApplication.run(Api2DocDemoApp.class, args);
}

}

给 Controller 类上添加文档注解

然后我们在 RestController 类添加 @Api2Doc 注解，在需要有文档说明的地方
添加 @ApiComment 注解即可，如下所示：

package com.terran4j.demo.api2doc;

import com.terran4j.commons.api2doc.annotations.Api2Doc;
import com.terran4j.commons.api2doc.annotations.ApiComment;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@Api2Doc(id = "demo1", name = "用户接口1")
@ApiComment(seeClass = User.class)@RestController
@RequestMapping(value = "/api2doc/demo1")
public class UserController1 {

@ApiComment("添加一个新的用户。")
@RequestMapping(name = "新增用户",
value = "/user", method = RequestMethod.POST)
public User addUser(String group, String name,
@ApiComment("用户类型") UserType type) {
return null; // TODO:  还未实现。
}
}

这个方法的返回类型 User 类的定义为：

public class User {

@ApiComment(value = "用户id", sample = "123")
private Long id;

@ApiComment(value = "用户名", sample = "terran4j")
private String name;

@ApiComment(value = "账号密码", sample = "sdfi23skvs")
private String password;

@ApiComment(value = "用户所在的组", sample = "研发组")
private String group;

@ApiComment(value = "用户类型", sample = "admin")
private UserType type;

@ApiComment(value = "是否已删除", sample = "true")
@RestPackIgnore
private Boolean deleted;

@ApiComment(value = "创建时间\n也是注册时间。")
private Date createTime;

// 省略  getter / setter 方法。
}

以及 type 属性的类型，也就是 UserType 类的定义为：

package com.terran4j.demo.api2doc;

import com.terran4j.commons.api2doc.annotations.ApiComment;

public enum UserType {

@ApiComment("管理员")
admin,

@ApiComment("普通用户")
user
}

编写好代码后，我们运行 main 函数，访问 Api2Doc 的主页面：

http://localhost:8080/api2doc/home.html

文档页面如下：





说明 Api2Doc 服务起作用了，就是这么简单！

@Api2Doc 注解详述

Api2Doc 一共有 3 个注解：@Api2Doc、@ApiComment 及 @ApiError 。

@Api2Doc 用于对文档的生成进行控制。

@Api2Doc 修饰在类上，表示这个类会参与到文档生成过程中，Api2Doc 服务
会扫描 Spring 容器中所有的 Controller 类，只有类上有 @Api2Doc 的类，
才会被生成文档，一个类对应于文档页面左侧的一级菜单项，@Api2Doc 的
name 属性则表示这个菜单项的名称。

@Api2Doc 也可以修饰在方法，不过在方法上的 @Api2Doc 通常是可以省略，
Api2Doc 服务会扫描这个类的所有带有 @RequestMapping 的方法，
每个这样的方法对应文档页面的左侧的二级菜单项， 菜单项的名称取
@RequestMapping 的 name 属性，当然您仍然可以在方法上用 @Api2Doc
的 name 属性进行重定义。

@ApiComment 注解详述

@ApiComment 用于对 API 进行说明，它可以修饰在很多地方：

修饰在类上，表示对这组 API 接口进行说明；

修饰在方法上，表示对这个 API 接口进行说明；

修饰在参数上，表示对这个 API 接口的请求参数进行说明；

修饰在返回类型的属性上，表示对这个 API 接口的返回字段进行说明；

修饰在枚举项上，表示对枚举项进行说明；

如果相同名称、相同意义的属性或参数字段，其说明已经在别的地方定义过了，
可以用 @ApiComment 的 seeClass 属性表示采用指定类的同名字段上的说明信息，
所以如这段代码：

@Api2Doc(id = "demo1", name = "用户接口1")
@ApiComment(seeClass = User.class)@RestController
@RequestMapping(value = "/api2doc/demo1")
public class UserController1 {

@ApiComment("添加一个新的用户。")
@RequestMapping(name = "新增用户",
value = "/user", method = RequestMethod.POST)
public User addUser(String group, String name, UserType type) {
return null; // TODO:  还未实现。
}
}

虽然 group, name ,type 三个参数没有用 @ApiComment 进行说明，
但由于这个类上有 @ApiComment(seeClass = User.class) ，
因此只要 User 类中有 group, name ,type 字段并且有 @ApiComment 的说明就行了。

@ApiError 注解详述

@ApiError 用于定义错误码，有的 API 方法在执行业务逻辑时会产生错误，
出错后会在返回报文包含错误码，以方便客户端根据错误码作进一步的处理，
因此也需要在 API 文档上体现错误码的说明。

如下代码演示了 @ApiError 的用法：

@Api2Doc(id = "demo", name = "用户接口", order = 0)
@ApiComment(seeClass = User.class)@RestController
@RequestMapping(value = "/src/test/resources/demo")
public class UserController {

@Api2Doc(order = 50)
@ApiComment("根据用户id，删除指定的用户")
@ApiError(value = "user.not.found", comment = "此用户不存在！")
@ApiError(value = "admin.cant.delete", comment = "不允许删除管理员用户！")
@RequestMapping(name = "删除指定用户",
value = "/user/{id}", method = RequestMethod.DELETE)
public void delete(@PathVariable("id") Long id) {
}
}

@ApiError 的 value 属性表示错误码，comment 表示错误码的说明。

错误码信息会显示在文档的最后面，效果如下所示：

给文档菜单项排序

我们可以用 @Api2Doc 中的 order 属性给菜单项排序，order 的值越小，
该菜单项就越排在前面，比如对于这段代码：

package com.terran4j.demo.api2doc;

import com.terran4j.commons.api2doc.annotations.Api2Doc;
import com.terran4j.commons.api2doc.annotations.ApiComment;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@Api2Doc(id = "demo2", name = "用户接口2", order = 1)
@ApiComment(seeClass = User.class)@RestController
@RequestMapping(value = "/api2doc/demo2")
public class UserController2 {

@Api2Doc(order = 10)
@ApiComment("添加一个新的用户。")
@RequestMapping(name = "新增用户",
value = "/user", method = RequestMethod.POST)
public User addUser(
@ApiComment("用户组名称") String group,
@ApiComment("用户名称") String name,
@ApiComment("用户类型") UserType type) {
return null; // TODO:  还未实现。
}

@Api2Doc(order = 20)
@ApiComment("根据用户id，查询此用户的信息")
@RequestMapping(name = "查询单个用户",
value = "/user/{id}", method = RequestMethod.GET)
public User getUser(@PathVariable("id") Long id) {
return null; // TODO:  还未实现。
}

@Api2Doc(order = 30)
@ApiComment("查询所有用户，按注册时间进行排序。")
@RequestMapping(name = "查询用户列表",
value = "/users", method = RequestMethod.GET)
public List<User> getUsers() {
return null; // TODO:  还未实现。
}

@Api2Doc(order = 40)
@ApiComment("根据指定的组名称，查询该组中的所有用户信息。")
@RequestMapping(name = "查询用户组",
value = "/group/{group}", method = RequestMethod.GET)
public UserGroup getGroup(@PathVariable("group") String group) {
return null; // TODO:  还未实现。
}
}

显示的结果为：



在类上的 @Api2Doc 同样可以给一级菜单排序，规则是一样的，这里就不演示了。

补充自定义文档

有时候光有自动生成的 API 文档似乎还不太完美，或许我们想补充点别的什么东西，
比如： 对项目的背景介绍、技术架构说明之类，那这个要怎么弄呢？

Api2Doc 允许用 md 语法手工编写文档，并集成到自动生成的 API 文档之中，方法如下：

首先，要在类上的 @Api2Doc 定义 id 属性，比如对下面这个类：

package com.terran4j.demo.api2doc;

import com.terran4j.commons.api2doc.annotations.Api2Doc;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api2Doc(id = "demo3", name = "用户接口3")
@RestController
@RequestMapping(value = "/api2doc/demo3")
public class UserController3 {

@Api2Doc(order = 10)
@RequestMapping(name = "接口1", value = "/m1")
public void m1() {
}

@Api2Doc(order = 20)
@RequestMapping(name = "接口2", value = "/m2")
public void m2() {
}
}

@Api2Doc(id = "demo3", name = "用户接口3") 表示：对应的一级菜单“用户接口3”
的 id 为 demo3。

然后，我们在 src/main/resources 中创建目录 api2doc/demo3，
前面的 api2doc 是固定的，后面的 demo3 表示这个目录中的文档是添加到
id 为 demo3 的一级文档菜单下。

然后我们在 api2doc/demo3 目录中编写 md 格式的文档，如下图所示：



文件名的格式为 ${order}-${文档名称}.md，即 - 号前面的数字表示这个文档的排序，
与 @Api2Doc 中的 order 属性是一样的，而 - 号后面是文档名称，也就是二级菜单的名称。

因此，最后文档的显示效果为：



看，手工编写的补充文档与自动生成的 API 文档，通过 order 进行排序组合在一起，
看起来毫无违和感。

定制文档的欢迎页

每次访问文档页面 http://localhost:8080/api2doc/home.html 时，
中间的内容是非常简单的一句：

欢迎使用 Api2Doc ！

这似乎有点不太好，不过没关系，我们可以编写自己的欢迎页。

方法很简单，在 src/main/resources 目录的 api2doc 目录下，创建一个名为
welcome.md 的文件（这个名称是固定的），然后用 md 语法编写内容就可以。

配置文档的标题及图标

可以在 application.yml 中配置文档的标题及图标，如下所示：

api2doc:
title: Api2Doc示例项目——接口文档
icon: https://spring.io/img/homepage/icon-spring-framework.svg

图标为一个全路径 URL，或本站点相对路径 URL 都行。

配置后的显示效果为：

关闭 Api2Doc 服务

您在 application.yml 中配置 api2doc.enabled 属性，以开启或关闭 Api2Doc 服务，如：

# 本地环境
api2doc:
title: Api2Doc示例项目——接口文档
icon: https://spring.io/img/homepage/icon-spring-framework.svg
---
# 线上环境
spring:
profiles: online

api2doc:
enabled: false

api2doc.enabled 为 false 表示关闭 Api2Doc 服务，不写或为 true 表示启用。

由于 Api2Doc 服务没有访问权限校验，建议您在受信任的网络环境（如公司内网）
中才启用 Api2Doc 服务。