yapidoc-cli v1.0.2

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文档