背景
系統(tǒng)開發(fā)過程中，必然少不了文檔，而在互聯(lián)網(wǎng)應(yīng)用系統(tǒng)開發(fā)中，API接口文檔則更是必不可少。
YApi
YApi 是高效、易用、功能強(qiáng)大的 api 管理平臺，旨在為開發(fā)、產(chǎn)品、測試人員提供更優(yōu)雅的接口管理服務(wù)?？梢詭椭_發(fā)者輕松創(chuàng)建、發(fā)布、維護(hù) API，YApi 還為用戶提供了優(yōu)秀的交互體驗，開發(fā)人員只需利用平臺提供的接口數(shù)據(jù)寫入工具以及簡單的點擊操作就可以實現(xiàn)接口的管理。
總之，很厲害，官網(wǎng)地址 http://yapi.demo.qunar.com/
本地部署
官方文檔環(huán)境要求：
- nodejs（7.6+)
- mongodb（2.6+）
官方文檔安裝方式
- 方式一. 可視化部署[官方推薦]
- 方式二. 命令行部署
實機(jī)安裝：
- 操作系統(tǒng)：CentOS 8.1
- nodejs：v12.16.1
- mongodb：v4.0.10
-
根據(jù)官網(wǎng)提示，使用命令行安裝，執(zhí)行命令
cd /home
mkdir yapi
cd yapi
wget http://registry.npm.taobao.org/yapi-vendor/download/yapi-vendor-1.8.8.tgz
tar zxvf yapi-vendor-1.8.8.tgz
cp package/config_example.json ./config.json //復(fù)制完成后請修改相關(guān)配置
cd package
npm install --production --registry https://registry.npm.taobao.org
npm run install-server //安裝程序會初始化數(shù)據(jù)庫索引和管理員賬號，管理員賬號名可在 config.json 配置
pm2 start server/app.js --name "YApi" //啟動服務(wù)器
-
打開ip+config.json里配置的端口號就能夠正常訪問了。
-
配置郵箱
打開項目目錄 config.json 文件，新增 mail 配置， 替換默認(rèn)的郵箱配置
{
"port": "*****",
"adminAccount": "********",
"db": {...},
"mail": {
"enable": true,
"host": "smtp.163.com", //郵箱服務(wù)器
"port": 465, //端口
"from": "***@163.com", //發(fā)送人郵箱
"auth": {
"user": "***@163.com", //郵箱服務(wù)器賬號
"pass": "*****" //郵箱服務(wù)器密碼
}
}
}
如何申請STMP服務(wù)器賬號和密碼可以參考下面的教程：如何開通電子郵箱的SMTP功能
-
禁止注冊
在 config.json 添加 closeRegister:true 配置項,就可以禁止用戶注冊 yapi 平臺，修改完成后，請重啟 yapi 服務(wù)器。
這個地方禁用的時候要注意，管理員是沒法添加用戶的，只能等成員們都注冊完了，再進(jìn)行關(guān)閉注冊功能。
{
"closeRegister":true
}
-
版本通知
（v1.3.19+ 增加）在 config.json 添加 "versionNotify": true 配置項，就可以開啟版本通知功能，默認(rèn)為 false，修改完成后，請重啟 yapi 服務(wù)器。
{
"versionNotify": true
}
最終，config.json文件內(nèi)容如下圖
最后重啟服務(wù)
pm2 restart YApi
注意：
部署的時候，有幾個地方需要注意：
如果使用可視化部署：
a. 在 yapi-cli 安裝目錄下 /src/commands/server.js 里，有一句應(yīng)該是官方統(tǒng)計代碼，如果不想被官方統(tǒng)計到，可以進(jìn)行注釋（但不推薦，開源不易，需要共同支持 ??）
b. 我這邊安裝時報了數(shù)據(jù)庫連接錯誤，導(dǎo)致放棄了可視化安裝選用了命令行部署，分析應(yīng)該是mongodb的版本問題，如果實際安裝的時候沒報錯，可以忽略
升級：
升級項目版本是非常容易的，并且不會影響已有的項目數(shù)據(jù)，只會同步 vendors 目錄下的源碼文件。
cd {項目目錄}
yapi ls //查看版本號列表
yapi update //升級到最新版本
yapi update -v v1.1.0 //升級到指定版本
使用
大體步驟：
- 新增項目
- 新增分組
- 新增接口，編輯詳情
- 接口測試（測試需要安裝Chrome插件）[谷歌請求插件詳細(xì)安裝教程]
使用步驟總體來說還是很簡單的
導(dǎo)入Swagger及與Swagger同步
這兩個功能還未進(jìn)行測試
導(dǎo)出文檔
可以選擇多種輸出格式，還是很方便的
但是，發(fā)現(xiàn)不能夠?qū)С龀蓋ord文檔。一般留底或者交付客戶的時候會需要word文檔，可是YApi不能導(dǎo)出成word，就在網(wǎng)上找尋了一下有沒有格式轉(zhuǎn)換的工具。發(fā)現(xiàn)一個叫pandoc的工具功能好像無比強(qiáng)大。于是乎安裝嘗試了一下，通過YApi生成.html文件，然后通過pandoc轉(zhuǎn)換成.docx文件。
轉(zhuǎn)換：
pandoc -s api.html -o api.docx
看起來效果還不錯，這里建議用導(dǎo)出的html文件轉(zhuǎn)docx文件效果會更好一些。
總結(jié)
項目開發(fā)中，可以使用YApi編寫文檔、定義接口，并且在開發(fā)過程中直接進(jìn)行測試、生成測試報告等。項目交付時，可以將接口導(dǎo)出成文件的形式進(jìn)行留底和交付。
部分內(nèi)容轉(zhuǎn)自 https://github.com/YMFE/yapi
