一、为什么用yapi
- yapi基于文档注释生成，没有代码的入侵。
- 同一个工程的接口文档可以导出多个项目中，分权限查看。
- 可以本地化部署，统一的接口文档，支持其他的文档接入。
- 有idea插件支持，自动导出。
二、安装部署
- 安装
这里只是记录个人操作过程，详情可看官网，连接在这里。
注意：要先配置好再启动，启动后超管默认的密码在启动日志里面。配置文档/data/yapi/vendors/config.json参考以下：
{
"port": "16888",
"adminAccount": "[email protected]",
"closeRegister":true,
"timeout":120000,
"db": {
"servername": "127.*.*.*",
"DATABASE": "yapi",
"port": 1666,
"user": "yapi111",
"pass": "yapi111",
"authSource": ""
},
"mail": {
"enable": false,
"host": "smtp.163.com",
"port": 465,
"from": "***@163.com",
"auth": {
"user": "***@163.com",
"pass": "*****"
}
}
}
部署过程如下：
mkdir /data/yapi
cd /data/yapi
git clone https://github.com/YMFE/yapi.git vendors //或者下载 zip 包解压到 vendors 目录（clone 整个仓库大概 140+ M，可以通过 `git clone --depth=1 https://github.com/YMFE/yapi.git vendors` 命令减少，大概 10+ M）
cp vendors/config_example.json ./config.json //复制完成后请修改相关配置
cd vendors
npm install --production --registry https://registry.npm.taobao.org
npm run install-server //安装程序会初始化数据库索引和管理员账号，管理员账号名可在 config.json 配置
node server/app.js //启动服务器后，请访问 127.0.0.1:{config.json配置的端口}，初次运行会有个编译的过程，请耐心等候
- 后台运行
目前只做了nohup启动，后期可做成服务，加入到系统自启动中。
cd /data/yapi/vendors
nohup node server/app.js > runoob.log 2>&1 &
- 账号添加
方式一：开放首页注册功能，默认是开启的。
方式二：关闭注册功能，从数据中添加。可通过配置文件修改"closeRegister":true关闭注册功能，通过以下代码实现添加。
#角色类型，目前了解到两种，其他以后补充
guest #访客
admin #超级管理员
#获取用户
db.getCollection("user").find({})
#修改用户角色
db.user.update({"_id":2}, {$set: {"role":"admin"}});
db.user.update({"_id":20}, {$set: {"role":"guest"}});
#添加用户
db.user.insert({
"_id" : NumberInt(22),
"study" : true,
"type" : "site",
"username" : "test",
"password" : "b24bfd3584d83d82192239ace3bef9b7489136ad", #12345678
"email" : "[email protected]",
"passsalt" : "j9bklcsuq6",
"role" : "guest",
"add_time" : NumberInt(new Date().getTime() /1000),
"up_time" : NumberInt(new Date().getTime() /1000),
"__v" : NumberInt(0)
});
三、idea中使用。
我使用的插件是EasyYapi，这里就不详细介绍插件的使用了。如果我们要个性话的配置文档的输出，可以在工程根目录加上文件.easy.api.config，在文件中就可以个性话定制输出了，eg: field.ignore=#ignore
以下主要记录下项目运用中的主要关注点：
- 使用
@module app，可以很方便的将文档输出到指定的项目。
/**
* 首页接口
*
* @module app
* @Author xxx
* @Date 2022/12/6 11:26
* @description
*/
- 使用
@ignore，可以忽略不输出到文档中。
/**
* 条件转换
*
* @ignore
*/
String transform;
- 很多时候接口都是需要登录设置token的，方便后续的接口调用。
代码如下：
context.requestHeader.Authorization = storage.getItem('token');
if (context.responseData && context.responseData.data && context.responseData.data.token) {
storage.setItem("token", context.responseData.data.token)
}