曾经看过这样一个笑话：程序员最讨厌写文档，比这个还讨厌的事情就是，别人居然不写文档。
文档的确是个令猿头疼的东西哇，但是文档的重要性也是不言而喻。这里就给大家安利两款比较好用的接口文档生成工具：
- apidoc 比较好用的静态生成工具，生成静态api文档非常合适；
- swagger功能强大的动态api工具，带有调试功能，knife4j是对swaggerUI封装的优化，更适合国人风格；
- Japidocs 新开源的静态生成工具用的人虽然没有上面两个多，但是只需要java环境即可，也是不错的api生成工具，值得尝试。
1. apidoc
简介
apidoc是一款可以由源代码中的注释直接自动生成api接口文档的工具，它几乎支持目前主流的所有风格的注释。
使用
首先你的环境必须要安装了node.js.然后通过以下的命令安装apidoc：
npm install apidoc -g
在你的项目根目录下添加apidoc.json文件，这个文件主要包含一些项目的描述信息，例如标题、介绍、版本等。
1
2
3
4
5
6
7
8
|
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
1234567
|
在你的代码注释里加入apidoc的注解，例如这样子：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
/**
* @apiGroup Product
* @api {GET} /product/{id} 查询一个产品
* @apiDescription 指定产品id , 删除产品的全部信息，包括关联的schema
* @apiParam {String} id 产品id(必填*)
* @apiSuccessExample SuccessExample
* HTTP/1.1 200
* {
* id: 'xxx',
* modelId: 'xxxxx',
* name: 'xxx',
* intro: 'xxxx'
* }
* @apiErrorExample ErrorExample
* HTTP/1.1 600
* 具体的异常信息
*/
@GetMapping("/{id}")
public Product getOneProduct(@PathVariable String id)
{
return productServ.findOne(id);
}
12345678910111213141516171819202122
|
常用的一些注解如下：
1
2
3
4
5
6
7
8
9
|
@api 定义API的请求方法、路径和名字
@apiDescription 定义API的描述
@apiGroup 定义API的分组
@apiParam 定义API的参数
@apiParamExample 参数请求的事例
@apiVersion 版本
@apiErrorExample API错误示例
@apiSuccessExample API正常示例
12345678
|
然后就可以利用apidoc的命令来生成接口文档了：
然后当前目录下会生成一个新的apidoc目录，就是新生成的接口文档文件。
打开 index.html 即可看到生成的接口文档：
2. swagger
在这里俺用 springBoot 整合swagger2 做了个Restful Api 的接口小demo
github 源码传送门☛☛☛
首先项目中得添加swagger2的依赖：
1
2
3
4
5
6
7
8
9
10
11
12
13
|
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
123456789101112
|
创建swagger2 的配置类：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
|
@Configuration
@EnableSwagger2
public class SwaggerConfig
{
public Docket createApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.miao.springbootswagger"))
.paths(PathSelectors.any())
.build();
}
// 创建api的基本信息
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("springBoot 整合 Swagger2 实例")
.description("更多技术内容分享见博客：https://blog.csdn.net/qq_24871519")
.termsOfServiceUrl("https://blog.csdn.net/qq_24871519")
.version("1.0")
.build();
}
}
1234567891011121314151617181920212223
|
为接口添加swagger的注解：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
|
@RestController
@RequestMapping("/user")
public class UserController
{
private static Map<String, User> users=new ConcurrentHashMap<>();
@ApiOperation(value = "添加用户", notes = "添加一条用户信息")
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
@PostMapping("/add")
public User add(User user){
String id=UUID();
while(users.containsKey(id)){
id=UUID();
}
user.setId(id);
users.put(id, user);
return user;
}
@ApiOperation(value = "获取一个用户", notes = "根据用户id获取用户信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String")
@GetMapping("/{id}")
public User getOne(@PathVariable String id){
if(!users.containsKey(id)){
return null;
}
return users.get(id);
}
@ApiOperation(value = "获取所有用户信息列表")
@GetMapping("/")
public List<User> getUsers(){
return new ArrayList<>(users.values());
}
@ApiOperation(value = "更新用户信息")
@ApiImplicitParam(name = "user", value = "用户信息实体",required = true, dataType = "User")
@PutMapping("/")
public User updateOne(User u){
User tmp = users.get(u.getId());
if(tmp == null){
return null;
}
if(u.getName()!=null){
tmp.setName(u.getName());
}
if(u.getAge() != null){
tmp.setAge(u.getAge());
}
return tmp;
}
@ApiOperation(value = "删除用户")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "String")
@DeleteMapping("/{id}")
public void delete(@PathVariable String id){
if(users.containsKey(id)){
users.remove(id);
}
}
private String UUID(){
return UUID.randomUUID().toString().replace("-", "");
}
}
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465
|
上述都完成后，启动springBoot 项目，访问 http://localhost:/swagger-ui.html 即可访问接口文档页面，具体页面如下：
3、JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具
JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具。
编写和维护API文档这个事情，对于后端程序员来说，是一件恼人但又不得不做的事情，我们都不喜欢写文档，但除非项目前后端代码都是自己写的，否则API文档将是前后端协作中一个不可或缺的沟通界面。
既然不可避免，那就想办法弄个轮子吧。人生苦短，必须偷懒。
相比Swagger要写一堆注解，Spring RestDocs需要写测试用例，才能生成API文档。JApiDocs 具有无痛集成的特点，你只需花几分钟就能知道它怎么用了。
快速开始
要使得JApiDcos正确工作，你写的代码应该是像下面的样子的：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
|
/**
* 用户接口
*/
@RequestMapping("/api/user/")
@RestController
publicclassUserController{
/**
* 用户列表
*@paramlistForm
*/
@RequestMapping(path ="list", method = {RequestMethod.GET, RequestMethod.POST} )
publicApiResult> list(UserListForm listForm){
returnnull;
}
/**
* 保存用户
*@paramuserForm
*/
@PostMapping(path ="save")
publicApiResult saveUser(@RequestBodyUserForm userForm){
returnnull;
}
}
|
我们给Controller类和方法加上必要的注释，给接口方法返回相关的对象类型。是的，这样JApiDocs就能解析到相关的接口信息了，就跟我们平时写的代码是差不多的，但要注意，你要通过@param来告诉JApiDocs接口的参数，但在IDE的帮助下，这个工作将是轻松愉悦的：
然后你在任意一个main入口方法执行下面的代码就可以生成文档了：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
DocsConfigconfig= 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); // 执行生成文档
|
接下来你只管好好写代码，生成Api文档的工作就可以交给JApiDocs了，你不需要再为额外编写和维护文档而烦恼。
功能特性
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/