我们的故事

搭建接口文档和接口mock服务

接口描述文档，前后使用过confluence（太重），研究过gitbook（有点像github，私有需要收费），最后选择了apiblueprint。apiblueprint是一种基于markdown的接口语言定义，有诸多基于该语言的工具。如：aglio提供页面绘制服务，drakov提供接口模拟服务等。下文将描述我是怎么使用这两个工具来提供接口服务的。

apiblueprint

以下是文档举例，具体语法可参照官方文档https://apiblueprint.org/

FORMAT: 1A
HOST: https://mock.**.com

# 微信服务接口文档

提供微信基础接口和微信相关活动的接口

## Group 微信基础接口

### 读取微信授权路径 [GET /weChat/getOAuthUrl{?appId,oAuthType}]

  + Parameters
    + appId: wxd26d9e82edd77049 - 微信应用的Id
    + oAuthType: WECHAT_INNER - 微信授权类型:微信内授权(WECHAT_INNER), web页面扫码授权(WEB_QRCODE)

  + Response (application/json)
        {
              "error": null,
              "result": "https://open.weixin.qq.com/connect/qrconnect?appid=wxd26d9e82edd77049&redirect_uri=REDIRECT_URI&response_type=code&scope=snsapi_login&state=STATE#wechat_redirect"
        }

 

aglio

使用方法参照官方文档https://github.com/danielgtaylor/aglio

-i input文档

-o output文档

aglio -i README.md -o doc-booking.html

此命令即可生成标准格式的html文档

drakov

使用方法参照官方文档https://github.com/Aconex/drakov

-f apiblueprint原始文档

--watch 监听文档变化，自动更新mock服务

--method POST 支持POST调用

/usr/bin/drakov -f "/data/doc/origin/*/README.md" --watch  --method POST

此命令即可开启mock服务

jenkins

jenkins配置代码库，自动拉取接口文档，点击即可将最新的文档发布到接口文档库，接口文档库使用的nginx服务，直接index文档目录，这一块还有优化空间。

supervisor

为了更好地对drakov进程进行管理，使用了supervisor来托管drakov进程，配置文件如下

[program:mock]

command=/usr/bin/drakov -f "/data/doc/origin/*/README.md" --watch  --method POST

autostart=true

startsecs=5

autorestart=true

startretries=3

user=www-data

redirect_stderr=true

stdout_logfile=/data/log/supervisor/mock.livenaked.com.out

stdout_logfile_maxbytes=20MB

stdout_logfile_backups=10

yuxiang2013@gmail.com