更优雅的接口文档编写方式 — YApi

2020-03-24  本文已影响0人  丶听见下雨的声音

背景

系统开发过程中，必然少不了文档，而在互联网应用系统开发中，API接口文档则更是必不可少。

YApi

平台介绍

YApi 是高效、易用、功能强大的 api 管理平台，旨在为开发、产品、测试人员提供更优雅的接口管理服务。可以帮助开发者轻松创建、发布、维护 API，YApi 还为用户提供了优秀的交互体验，开发人员只需利用平台提供的接口数据写入工具以及简单的点击操作就可以实现接口的管理。

总之，很厉害，官网地址 http://yapi.demo.qunar.com/

本地部署

官方文档环境要求：

  • nodejs（7.6+)
  • mongodb（2.6+）

官方文档安装方式

  • 方式一. 可视化部署[官方推荐]
  • 方式二. 命令行部署

实机安装：

  • 操作系统：CentOS 8.1
  • nodejs：v12.16.1
  • mongodb：v4.0.10
  1. 根据官网提示，使用命令行安装，执行命令
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 //复制完成后请修改相关配置
cd package
npm install --production --registry https://registry.npm.taobao.org
npm run install-server //安装程序会初始化数据库索引和管理员账号，管理员账号名可在 config.json 配置
pm2 start server/app.js --name "YApi" //启动服务器
  1. 打开ip+config.json里配置的端口号就能够正常访问了。
访问效果
  1. 配置邮箱

打开项目目录 config.json 文件，新增 mail 配置， 替换默认的邮箱配置

{
  "port": "*****",
  "adminAccount": "********",
  "db": {...},
  "mail": {
    "enable": true,
    "host": "smtp.163.com",    //邮箱服务器
    "port": 465,               //端口
    "from": "***@163.com",     //发送人邮箱
    "auth": {
        "user": "***@163.com", //邮箱服务器账号
        "pass": "*****"        //邮箱服务器密码
    }
  }
}

如何申请STMP服务器账号和密码可以参考下面的教程：如何开通电子邮箱的SMTP功能

  1. 禁止注册

在 config.json 添加 closeRegister:true 配置项,就可以禁止用户注册 yapi 平台，修改完成后，请重启 yapi 服务器。
这个地方禁用的时候要注意，管理员是没法添加用户的，只能等成员们都注册完了，再进行关闭注册功能。

{
  "closeRegister":true
}
  1. 版本通知

（v1.3.19+ 增加）在 config.json 添加 "versionNotify": true 配置项，就可以开启版本通知功能，默认为 false，修改完成后，请重启 yapi 服务器。

{
  "versionNotify": true
}

最终，config.json文件内容如下图


config.json

最后重启服务

pm2 restart YApi
注意：

部署的时候，有几个地方需要注意：
如果使用可视化部署：
a. 在 yapi-cli 安装目录下 /src/commands/server.js 里，有一句应该是官方统计代码，如果不想被官方统计到，可以进行注释（但不推荐，开源不易，需要共同支持 😀）



b. 我这边安装时报了数据库连接错误，导致放弃了可视化安装选用了命令行部署，分析应该是mongodb的版本问题，如果实际安装的时候没报错，可以忽略


错误信息
升级：

升级项目版本是非常容易的，并且不会影响已有的项目数据，只会同步 vendors 目录下的源码文件。

cd {项目目录}
yapi ls //查看版本号列表
yapi update //升级到最新版本
yapi update -v v1.1.0 //升级到指定版本

使用

大体步骤：

  1. 新增项目
  2. 新增分组
  3. 新增接口，编辑详情
  4. 接口测试（测试需要安装Chrome插件）[谷歌请求插件详细安装教程]

使用步骤总体来说还是很简单的

新增接口
编辑详情
添加测试
导入Swagger及与Swagger同步

这两个功能还未进行测试

导出文档

可以选择多种输出格式，还是很方便的

但是，发现不能够导出成word文档。一般留底或者交付客户的时候会需要word文档，可是YApi不能导出成word，就在网上找寻了一下有没有格式转换的工具。发现一个叫pandoc的工具功能好像无比强大。于是乎安装尝试了一下，通过YApi生成.html文件，然后通过pandoc转换成.docx文件。

导出的html

转换：

pandoc -s api.html -o api.docx
转换后的docx

看起来效果还不错，这里建议用导出的html文件转docx文件效果会更好一些。

总结

项目开发中，可以使用YApi编写文档、定义接口，并且在开发过程中直接进行测试、生成测试报告等。项目交付时，可以将接口导出成文件的形式进行留底和交付。

部分内容转自 https://github.com/YMFE/yapi

上一篇下一篇

猜你喜欢

热点阅读