上一篇简单介绍了node命令行工具实用的第三方库,这一篇就看下实战结果
yapidoc-cli
说明
yapidoc-cli 是在apidoc文档编写的基础上,实现一键同步api文档到yapi的命令行工具,同时也提供swagger文档一键同步到yapi, api接口请按照apidoc 规范编写
npm install -g apidoc-swagger
npm install -g yapidoc-cli
使用文档
- 查看帮助文档
$ yapidoc-cli -h
用法: index.js <cmd> [options]
命令:
index.js ls 列出指定的api,默认所有
index.js build 生成生成swagger.json文档
index.js update 更新指定api接口到yapi,默认所有
选项:
--config, -c 指定配置文件 [字符串]
-v 显示版本号 [布尔]
-h 显示帮助信息 [布尔]
- 配置文件模板如下
{
"apidoc":{
"name": "Test API - This is my API",
"version": "1.0.0",
"description": "This is my very powerful API",
"title": "Test API - This is my API",
"url": "https://testapi.com"
},
"yapidoc":{
"token": "ssdfaskjfasfifsfnaskjfhaifnfk",
"host": "http://xxx.yapi.com",
"merge": "normal"
}
}
-
配置文件参数说明
apidoc : apidoc的配置项目详见apidoc.json
yapidoc: yapi的配置项
1. token : 每个项目都有唯一的标识 token,用户可以使用这个 token 值来请求 openapi 2. host:内网/外网部署的yapi地址 3. merge: normal, good, mergin, 默认为normal
-
设置配置文件
yapidoc-cli -c=你的配置文件
- 编写apidoc 文档, 如下
/**
* @apiDefine UserNotFoundError
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
/**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*
* @apiUse UserNotFoundError
*/
/**
* @api {put} /user/ Modify User information
* @apiName PutUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
* @apiParam {String} [firstname] Firstname of the User.
* @apiParam {String} [lastname] Lastname of the User.
*
* @apiSuccessExample Success-Response:
* HTTP/1.1 200 OK
*
* @apiUse UserNotFoundError
*/
- 编译生成文档
yapidoc-cli build -i=/d/selfProject/yapidoc-cli/test -o=/d/selfProject/yapidoc-cli/test -t=a
1. -i 项目api接口的目录
2. -o 编译结果输出目录(t=a时必填)
3. -t a表示apidoc s表示对swagger.json文件操作
4. 以上路径暂支持绝对路径
- 查看文档
$ yapidoc-cli ls -m=get -u=/user/
----------- api list --------------
url: /user/ method: put
$ yapidoc-cli ls
----------- api list --------------
url: /user/:id method: get
url: /user/ method: put
1. m http请求方法
2. u url
3. m 和 u 同时满足时,输出接口详情
4. m 和 u 不传,默认输出所有api列表
- 更新文档到yapi
$ yapidoc-cli update
----------- 接口更新结果:成功导入接口 0 个, 已存在的接口 2 个 --------------
----------- api list --------------
url: /user/:id method: get
url: /user/ method: put
1. 参数同ls
2. 同步指定的api到yapi,默认同步所有
- 说明
1. ls, update暂时还依赖于build,只有build成功后才能操作最新的api文档
- 有点绕,先这样了
命令行翻译工具
之前也写过一个命令行工具bdnote,命令行汉英互译,调用百度api完成,需自己注册百度开发者账号,获取自己的appid和key,具体看源码吧,就闹着玩
https://github.com/AviorAlong/postItNotes
来公众号撩骚,获取跟多资讯