接口文档管理工具(yapi的使用)

一、API管理工具

[推荐-官方描述]使用 YApi 管理 API 文档，测试， mock
参考URL: https://juejin.im/post/5acc879f6fb9a028c42e8822
API管理之YApi实现前后端高度分离
https://www.cnblogs.com/dreamsqin/p/11972789.html

企业一般都采用自建工具，自己维护一套 API 接口管理工具，比较热门的有：

• yapi：去哪儿出品，线上演示地址 http://yapi.demo.qunar.com
• RAP / rap2-delos + rap2-dolores：阿里出品，线上演示地址 http://rap2.taobao.org/
• easy-mock：线上演示地址 https://easy-mock.com/
• swagger：国外比较热门的接口管理工具

相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。

在后端开发接口过程中，开发和测试是必不可少的环节。按以往的做法，接口文档管理因为没有跟开发和测试整合到一起被孤立，导致后端维护对于他们冗杂繁琐的文档，是件收益很低的事情。

接口的维护管理非常耗时，大概占用了30%开发时间。后端程序员要维护对于他们冗余的文档，前端程序员又因为后端开发提供的文档不准确，导致浪费了大量的时间。

二、yapi 接口管理工具功能

API管理之YApi实现前后端高度分离
参考URL: https://www.cnblogs.com/dreamsqin/p/11972789.html

YApi是由去哪网前端团队开源的一款接口管理工具，功能强大，可以轻松内网部署。同时支持docker部署，使用成本低，安全性能高。

权限管理

由于接口管理操作频繁，传统的金字塔管理模式中层层审批严重影响开发效率，所以YApi 采用扁平化管理模式，其中超级管理员拥有最高权限，并将权限分配给若干组长（包括分组组长和项目组长），未被加入分组和项目的用户称为游客。权限一览表如下：

所有账号分成2个维度管理和使用yapi，一个是分组的维度，一个项目的维度，两者不冲突，管理的维度不同。比如一个账号既可以是分组组长，也可以是项目组长。

项目管理页面功能

创建分组后，可在分组中新建项目。
点击具体项目，进入,如下图

接口

• 接口列表：进行接口管理；
• 测试集合：测试用例管理，方便后续进行自动化测试，自动化测试过程可参见下图流程；
  

接口创建

进入项目内，左边导航可以看到接口列表， 可以根据实际情况对接口进行分类，也可以只使用默认的“公共接口"分类"。

配置接口的Reqeust和Response，支持多种形式，除开mock固定返回值，yapi还为我们提供了丰富的mock变量
例如@name:返回随机的人名，@id返回随机的id，@string返回随机的字符串，@ip返回随机IP，@time返回随机时间，yapi提供了上百种mock参数。

接口配置管理界面

* 预览

查看接口信息（包括基本信息、请求参数、返回数据）

• 编辑

接口管理的主体，用于请求参数和返回数据的设置与可视化mock，支持常用数据类型string、number、array、object、boolean、integer的模拟，其中字段业务类型支持47种，例如@image、@url、@id、@datetime、@email、@province等。
还可对字段进行高级配置，包括默认值、长度控制、大小控制、正则过滤、枚举等。

• 运行

针对单个接口的个性化测试，可将测试配置保存至测试集合。

• 高级Mock

Mock 期望根据设置的请求过滤规则，返回期望数据；
自定义 Mock 脚本可以根据用户请求的参数修改返回内容；

动态

查看该项目下接口的变更动态，可以具体到变更人、变更时间、变更接口、变更操作（改动详情）；

成员管理

控制成员的新增、删除、邮件接收、角色权限

数据管理

支持数据的导入导出，目前数据导入格式支持：Postman、HAR、Swagger、json；导出格式支持：html、markdown、json、swaggerjson。

设置

项目配置：项目基本信息配置，这里可以总控是否开启项目中接口变动的邮件通知；
环境配置：配置项目接口测试的后端环境，支持添加多个环境；
请求配置：可以通过自定义 js 脚本方式改变请求的参数和返回的 response 数据；
token配置：每个项目都有唯一的标识 token，用户可以使用这个 token 值来请求 openapi；
全局mock脚本：方便用户在项目层面上全局设置公共的mock数据，例如全局接口返回code：0；

三、 docker安装yapi

0. yapi使用的mongodb，首先安装mongodb
   参考URL: https://blog.csdn.net/inthat/article/details/104208963

注意给mongodb配置账号密码。

1. 加载制作好的yapi docker镜像。

docker load  -i yapi_docker_image.tar

2. 运行docker镜像
   如下命令启动docker镜像，先访问9090端口配置初始化yapi，3000端口配置yapi访问接口

docker run -dit -p 9090:9090 -p 3000:3000 yapi

另：docker镜像的导入和导出,

# 
docker save -o yapi_docker_image.tar she/yapi:v1.8.5
# 其中-i表示从文件输入
docker load  -i yapi_docker_image.tar

三、使用流程

1. yapi安装，并初始化

2. 管理员登录
   安装初始化正常的话，应该能正常访问到，默认密码(ymfe.org) 登录系统（默认密码可在个人中心修改）
   登录账号admin@admin.com，密码 ymfe.org

3. 创建用户
   要先创建用户，要不然等会创建分组，分组组长选不了人。
   创建用户，可以通过登录界面，用户自己注册。管理员内部没有添加用户的界面。如果有批量创建用户需求，可以调注册页面对应的接口，自己编码创建。

4. 项目创建
   默认分组里面，只有一个分组，叫个人空间。如果使用默认的个人空间，那你的项目永远不会被别人看到，就失去了YAPI的意义。

   新建项目前一定要先添加分组，因为这个会涉及到后期的成员权限管理，将项目组的组长设置为自己或者项目负责人。
   
   新建项目时需要选中所属的项目组，项目组内的成员才有对应的权限使用项目中的接口。

5. 创建接口
   如果项目有独有特定特定前缀，可以 配置项目 接口基本路径 。这样每次新增接口不用再加改前缀，后面删除修改也好处理。

四、参考

yapi官方快速上手
https://hellosean1025.github.io/yapi/documents/index.html