前言
公司新来了个前端人员,之前的开发规范是一个人单项目开发,独立负责前后端项目,因此就基本没有编写接口文档。
但目前为了开发规范,所以转变开发模式为前后端开发。所以急需一个接口管理服务器,Yapi 的界面足够优美,也不会对代码入侵的特别严重,重要的是可以开源进行内网部署,因此敲定为 Yapi。
一、概述
YAPI是由去哪儿网移动架构组(简称YMFE,一群由FE、iOS和Android工程师共同组成的最具想象力、创造力和影响力的大前端团队)开发的可视化接口管理工具,是一个可本地部署的、打通前后端及QA的接口管理平台。YAPI旨在为开发、产品和测试人员提供更优雅的接口管理服务,可以帮助开发者轻松创建、发布和维护不同项目,不同平台的API。有了YAPI,我们可以很方便的测试、管理和维护多个项目的API接口,不像Swagger那样是随应用生和灭的(且线上环境下大多数须关闭),YAPI是一个独立的服务平台。
二、安装步骤
环境要求:
- nodejs(7.6+)
- mongodb(2.6+)
本机版本:
[root@localhost my-yapi]# cat /etc/redhat-release
CentOS Linux release 7.9.2009 (Core)
复制代码
2.1 安装nodejs
nodejs 的安装比较简单,可以和参考这篇文章:
2.2 安装mongodb
可以去官网下载其他版本:
我这里选用的是 mongodb 4.0.10 版本,然后上传到指定目录。
-
1、解压
[root@localhost package]# tar -xvf mongodb-linux-x86_64-4.0.10.tgz -C /opt/software/ 复制代码
-
2、重命名,配置环境变量
[root@localhost software]# mv mongodb-linux-x86_64-4.0.10/ mongodb [root@localhost software]# vim /etc/profile [root@localhost software]# source /etc/profile 复制代码
export MONGODB_HOME=/opt/software/mongodb export PATH=$MONGODB_HOME/bin 复制代码
-
3、创建文件夹
[root@localhost mongodb]# mkdir -p data/db [root@localhost mongodb]# mkdir -p logs [root@localhost mongodb]# ls bin data LICENSE-Community.txt logs MPL-2 README THIRD-PARTY-NOTICES THIRD-PARTY-NOTICES.gotools 复制代码
-
4、创建mongodb.conf 配置文件
dbpath = /opt/software/mongodb/data/db # 数据文件存放目录 logpath = /opt/software/mongodb/logs/mongodb.log # 日志文件存放目录 port = 27017 # 端口 fork = true # 以守护程序的方式启用,即在后台运行 noauth = true # 不进行安全验证 # auth=true # 需要认证。如果放开注释,就必须创建MongoDB的账号,使用账号与密码才可远程访问,第一次安装建议注释 bind_ip=0.0.0.0 # 允许远程访问,或者直接注释,127.0.0.1是只允许本地访问 复制代码
-
5、启动mongodb,并检查
[root@localhost mongodb]# bin/mongod -f mongodb.conf Error parsing INI config file: the options configuration file contains an invalid line '访问,第一次安装建议注释' try 'bin/mongod --help' for more information [root@localhost mongodb]# vim mongodb.conf [root@localhost mongodb]# bin/mongod -f mongodb.conf about to fork child process, waiting until server is ready for connections. forked process: 11068 child process started successfully, parent exiting [root@localhost mongodb]# ps -ef|grep mongodb root 11068 1 5 14:42 ? 00:00:00 bin/mongod -f mongodb.conf root 11270 58533 0 14:43 pts/1 00:00:00 grep --color=auto mongodb 复制代码
2.3 安装 Yapi-cli
-
1、直接在线安装
npm install -g yapi-cli --registry https://registry.npm.taobao.org yapi server 复制代码
-
2、访问对应 ip 页面
-
3、写上对应信息,部署成功。
如果失败了,可能是 yapi 的一个版本bug ,查看这篇文章:www.showdoc.com.cn/p/b9c1a4929…
-
4、进入yapi目录,启动服务器 node vendors/server/app.js
[root@localhost software]# ls java8 mongodb mysql8 my-yapi nacos nginx node12 redis6 [root@localhost software]# cd my-yapi/ [root@localhost my-yapi]# node vendors/server/app.js & log: -------------------------------------swaggerSyncUtils constructor----------------------------------------------- log: 服务已启动,请打开下面链接访问: http://127.0.0.1:3000/ log: mongodb load success... 复制代码
【注意】:此处 加个 & 是让 yapi 以后台的形式启动,不会关闭窗口后服务停止。
-
5、访问3000 端口,按照它给的账号,密码进行登录
2.4 docker 安装
参考:hub.docker.com/r/yapipro/y…
三、Yapi 玩法
3.1 添加分组
3.2 添加项目
3.3 安装浏览器插件
这里可以当成我们的postman 来测试,可以直接进行浏览器访问本地服务。
不过需要安装个 Yapi 跨域插件
测试接口
4.3 配置 token
- windows 下快速发布接口 alt + shift + e、
- mac 下快速发布接口: ctrl + e
4.4 注释demo
4.4.1 controller 层注释写法
/**
* 分类名称
* 分类备注/描述
*
* @module 归属项目
*/
@RestController
@RequestMapping(value = "/pathOfCtrl")
public class MockCtrl {
/**
* api名称
* api描述
* @param param1 参数1的名称或描述
* @param param2 可以用`@link`来表示当前参数的取值是某个枚举{@link some.enum.or.constant.class}
* @param param3 当目标枚举字段与当前字段名不一致,额外指定{@link some.enum.or.constant.class#property1}
* @return 响应描述
*/
@RequestMapping(value = "/pathOfApi1")
public Result methodName1(long param1,
@RequestParam String param2,
@RequestParam(required = false, defaultValue = "defaultValueOfParam3") String param3){
...
}
/**
* 默认使用`application/x-www-form-urlencoded`,
* 对于`@RequestBody`将使用`application/json`
* 可以用注解`@Deprecated`来表示api废弃
* 也可以用注释`@deprecated`
*
* @deprecated 改用{@link #methodName3(String)}
*/
@Deprecated
@RequestMapping(value = "/pathOfApi2")
public Result methodName2(@RequestBody MockDtoOrVo jsonModel){
...
}
/**
* 所有注释或者参数描述中都可以使用`@link`来引用另一个API
* 例如:
* 请先访问{@link #methodName4(String)}
* 也可以使用`@see`来引用另一个API
*
* @param param1 参数1的名称或描述 可以从{@link #methodName5(String)}中获得
* @see #methodName6(String)
* @deprecated 改用{@link #methodName7(String)}
*/
@Deprecated
@RequestMapping(value = "/pathOfApi3")
public Result methodName3(long param1){
...
}
...
}
复制代码
4.4.2 实体类注释写法
public class MockDtoOrVo {
/**
* 字段注释
*/
private Long field1;
private Double field2;//注释也可以写在这
/**
* 使用@see来说明当前字段的取值是某个枚举
* @see some.enum.or.constant.class
*/
private int field3;
/**
* 当目标枚举字段与当前字段名不一致,额外指定
* @see some.enum.or.constant.class#property1
*/
private int field4;
/**
* 可以用注解`@Deprecated`来表示字段被废弃
* 也可以用注释`@deprecated`
* @deprecated It's a secret
*/
@Deprecated
private int field5;
/**
* 如果使用javax.validation的话
* 可以使用@NotBlank/@NotNull表示字段必须
*/
@NotBlank
@NotNull
private String field6;
...
}
复制代码
4.5 常用配置规则
4.5.1 module
- 用于API分组
- 当无配置生效时, 默认使用当前模块/项目名
- 导出
postman
时,将为每个module
创建一个文件夹 - 导出
yapi
时,每个module
对应yapi
中的一个项目
demo:
/**
* Mock Apis
*
* @module mock
*/
@RestController
@RequestMapping(value = "mock")
public class MockCtrl {
}
复制代码
4.5.2 ignore
用于忽略方法 或忽略 类。
demo:
/**
* Mock Apis
*
* @ignore
*/
@RestController
@RequestMapping(value = "mock")
public class MockCtrl {
}
复制代码
4.5.3 json.rule.field.name
- 用于设置 输出 或输入的字段名不一样的情况
demo:
public class TestJsonFieldBean {
@JsonProperty("a")
private Long propertyA;
@SerializedName("b")
private Long propertyB;
}
复制代码
导出结果为:
名称 | 类型 | 是否必须 | 默认值 | 备注 | 其他信息 |
---|---|---|---|---|---|
a | integer | 非必须 | mock: @natural(0,10000) | ||
b | integer | 非必须 | mock: @natural(0,10000) |
4.5.4 json.rule.field.ignore
忽略字段
demo:
public class TestJsonIgnoreBean {
@Expose(serialize = true)
private Long shouldNotIgnoreForGson;
@Expose(serialize = false)
private Long shouldIgnoreForGson;
@JsonIgnore(false)
private Long shouldNotIgnoreForJackson;
@JsonIgnore
private Long shouldIgnoreForJackson;
}
复制代码
导出结果:
名称 | 类型 | 是否必须 | 默认值 | 备注 | 其他信息 |
---|---|---|---|---|---|
shouldNotIgnoreForGson | integer | 非必须 | mock: @natural(0,10000) | ||
shouldNotIgnoreForJackson | integer | 非必须 | mock: @natural(0,10000) |