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 中配置 api3doc.enabled 属性,以开启或关闭 Api2Doc 服务,如:
# 本地环境
api2doc:
title: Api2Doc示例项目——接口文档
icon: https://spring.io/img/homepage/icon-spring-framework.svg
---
# 线上环境
spring:
profiles: online
api2doc:
enabled: false
api3doc.enabled 为 false 表示关闭 Api2Doc 服务,不写或为 true 表示启用。
由于 Api2Doc 服务没有访问权限校验,建议您在受信任的网络环境(如公司内网)
中才启用 Api2Doc 服务。
TODO 列表
- 文档页面,“URL示例”改为“请求示例”,并支持所有的 METHOD 。
- 文档页面,“请求参数”表格,加上“参数位置”这一列。
- 文档页面,加上“返回示例”这一项,用 JSON 串表示。