分享一个好用的接口文档生成工具apipost，介绍两款好用的接口文档生成工具 apidoc & swagger
下面是关于
一、为什么要写接口文档？
正规的团队合作或者是项目对接，接口文档是非常重要的，一般接口文档都是通过开发人员写的。一个工整的文档显得是非重要。
项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发，项目维护中或者项目人员更迭，方便后期人员查看、维护
二、接口文档的格式
接口主要分为四部分：方法、uri、请求参数、返回参数
三、接口文档生成工具
apipost一款很不错的接口测试工具，它可以生成各种格式的接口文档，有在线版的，markdown格式和word格式的接口文档。
点击分享当前接口
分享
复制链接在浏览器中打开
下载其他格式的接口文档
word格式的接口文档（word只支持json格式的排版，所以百度放回的数据格式在word中显示不规范）
单个接口的word格式的接口文档可以免费下载，下载多个简单文档和一个项目的接口文档的时间就需要开会员了。
还有就是apipost下载多个word格式的接口文档的时候，每个接口是单独的接口文档需要合并。wps和office里面都有合并功能。
在插入中的对象中找到文件中的文字然后点击选择所有接口就可以合并了。
这就是接口文档生成工具apipost
曾经看过这样一个笑话：程序员最讨厌写文档，比这个还讨厌的事情就是，别人居然不写文档。
哈哈哈哈哈哈嗝！看来文档的确是个令猿头疼的东西哇，但是文档的重要性也是不言而喻。这里就给大家安利两款比较好用的接口文档生成工具：
1. apidoc
简介
apidoc是一款可以由源代码中的注释直接自动生成api接口文档的工具，它几乎支持目前主流的所有风格的注释。
使用
首先你的环境必须要安装了node.js.然后通过以下的命令安装apidoc：
npm install apidoc -g
在你的项目根目录下添加apidoc.json文件，这个文件主要包含一些项目的描述信息，例如标题、介绍、版本等。
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
1
2
3
4
5
6
7
在你的代码注释里加入apidoc的注解，例如这样子：
/**
* @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);
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
常用的一些注解如下：
@api 定义API的请求方法、路径和名字
@apiDescription 定义API的描述
@apiGroup 定义API的分组
@apiParam 定义API的参数
@apiParamExample 参数请求的事例
@apiVersion 版本
@apiErrorExample API错误示例
@apiSuccessExample API正常示例
1
2
3
4
5
6
7
8
然后就可以利用apidoc的命令来生成接口文档了：
然后当前目录下会生成一个新的apidoc目录，就是新生成的接口文档文件。
打开 index.html 即可看到生成的接口文档：
2. swagger
在这里俺用 springBoot 整合swagger2 做了个Restful Api 的接口小demo
github 源码传送门☛☛☛
首先项目中得添加swagger2的依赖：
<!-- 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>
1
2
3
4
5
6
7
8
9
10
11
12
创建swagger2 的配置类：
@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();
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
为接口添加swagger的注解：
@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("-", "");
}
}
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
上述都完成后，启动springBoot 项目，访问 http://localhost:/swagger-ui.html 即可访问接口文档页面，具体页面如下：
以上就是小编为大家整理的接口文档生成工具
版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。
发表评论
暂时没有评论，来抢沙发吧~