solar-apidoc
v0.0.2
Published
auto create api doc
Downloads
7
Readme
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平台“自动导入”页面查看