node package manager
Easy sharing. Manage teams and permissions with one click. Create a free org »

solar-apidoc

FIS API平台文档注释导入工具


这是什么

使用此工具轻松分析代码注释,生成API文档并导入到FIS API文档平台。

使用方式

  • npm install -g solar-apidoc
  • 使用规定格式在相应代码处添加注释
  • 在项目根目录执行 api-doc init初始化并填写必须参数,请先到http://solar.baidu.com/apidoc获取项目信息
  • 在项目根目录执行 api-doc start开始导入

您可以使用api-doc -h来查看使用帮助,使用api-doc -v查看插件版本。

注释语法

使用javaDoc注释标准,基于apidoc工具改造而成,支持所有主流语言哦,详细说明见apidoc官网

示例注释

/*
 * Basic Example
 *
 * 这是api doc的基本示例
 * 注释中没有@api的部分会被忽略
 */
 
/**
 * @api {get} /user/{id} 接口标题
 * @apiDescription 接口描述(可选)
 * @apiCategory 接口分类(可选)
 * 
 * @apiParam {String} [firstname]  可选姓名参数,无默认值
 * @apiParam {Number} id=123   必填姓名ID,默认值123
 *
 * @apiSuccessExample 成功:
 * HTTP/1.1 200 OK
 * {
 *   "firstname": "John",
 *   "lastname": "Doe"
 * }
 *
 * @apiErrorExample 失败:
 * HTTP/1.1 404 Not Found
 * {
 *   "error": "UserNotFound"
 * }
 *     
 * @apiErrorExample 连接失败:
 * {
 *   "error": "connect fail"
 * }
 */

配置说明

项目根目录下需填写初始化配置文件apidoc.json,基本配置如下:

  • project : 项目名称,在FIS API平台对应的项目名称,
  • version : 接口版本,如"0.0.1"
  • token : 权限校验码,请在FIS API平台“自动导入”页面查看