apidoc可以根据代码注释生成web api文档,支持大部分主流语言java javascript php coffeescript erlang perl python ruby go...,相对而言,web接口的注释维护起来更加方便,不需要额外再维护一份文档。
apidoc从注释生成静态html网页文档,不仅支持项目版本号,还支持api版本号。
安装
github: https://github.com/apidoc/apidoc
可以使用npm install apidoc -g进行安装,目前0.12.x/4.0都可以使用。
扫描二维码关注公众号,回复:
269306 查看本文章
apidoc支持Grunt,主页 https://github.com/apidoc/grunt-apidoc
1.需要安装nodejs环境,可以去官网下载http://nodejs.cn/download/
2(可选).修改npm全局目录,在cmd下
npm config set prefix "D:\www\nodejs"
3.全局目录安装apidoc,cmd下命令
npm install apidoc -g
4(可选).设置环境变量 将路径D:\www\nodejs设置到path上,cmd下set path=1111 清除下缓存,就不用重启了
使用
在项目下建一个apidoc.json文件,示例
{ "name" : "综合平台接口", "version": "1.0.0", "title": "综合平台接口", "url" : "http://center.ys.test", "sampleUrl": "http://center.ys.test", "description": "综合平台接口文档", "template": { "forceLanguage" : "zh_cn", "withCompare": true, "withGenerator": true }, "header": { "title": "综合平台说明", "filename": "header.md" }, "order" : [ "home", "homeApps", "user", "userList", "userInfo", "userDelete", "" ] }如果放入package.json中,相同的字段可以直接使用package.json的定义,额外的字段放入apidoc下
{ "name": "mysails", "private": true, "version": "1.0.0", "description": "xun's test project", "apidoc": { "title": "mysails" }, ... }代码注释说明 apidoc支持如下关键字
@api {method} path [title] 只有使用@api标注的注释块才会在解析之后生成文档,title会被解析为导航菜单(@apiGroup)下的小菜单 method可以有空格,如{POST GET} @apiGroup name 分组名称,被解析为导航栏菜单 @apiName name 接口名称,在同一个@apiGroup下,名称相同的@api通过@apiVersion区分,否者后面@api会覆盖前面定义的@api @apiDescription text 接口描述,支持html语法 @apiVersion verison 接口版本,major.minor.patch的形式 @apiIgnore [hint] apidoc会忽略使用@apiIgnore标注的接口,hint为描述 @apiSampleRequest url 接口测试地址以供测试,发送请求时,@api method必须为POST/GET等其中一种 @apiDefine name [title] [description] 定义一个注释块(不包含@api),配合@apiUse使用可以引入注释块 在@apiDefine内部不可以使用@apiUse @apiUse name 引入一个@apiDefine的注释块 @apiParam [(group)] [{type}] [field=defaultValue] [description] @apiHeader [(group)] [{type}] [field=defaultValue] [description] @apiError [(group)] [{type}] field [description] @apiSuccess [(group)] [{type}] field [description] 用法基本类似,分别描述请求参数、头部,响应错误和成功 group表示参数的分组,type表示类型(不能有空格),入参可以定义默认值(不能有空格) @apiParamExample [{type}] [title] example @apiHeaderExample [{type}] [title] example @apiErrorExample [{type}] [title] example @apiSuccessExample [{type}] [title] example 用法完全一致,但是type表示的是example的语言类型 example书写成什么样就会解析成什么样,所以最好是书写的时候注意格式化,(许多编辑器都有列模式,可以使用列模式快速对代码添加*号) @apiPermission name name必须独一无二,描述@api的访问权限,如admin/anyone示例
/** * @apiDefine sendError * @apiError {Number} status 响应状态 0表示失败 * @apiError {String} request 请求地址 * @apiError {String} error 错误说明 * @apiError {Number} error_code 错误编码 */ /** * @apiDefine sendSuccess * @apiSuccess {String} status 响应状态 1表示成功 * @apiSuccess {String} request 路径 * @apiSuccess {Aarray[]} data 数据 */ /** * @apiDefine defaultParam * @apiParam {String=web,server} platform web访问填web 服务器访问填server * @apiParam {String=json,xml} [format=json] 返回格式 默认json */ /** * @api {get} /home/api/apps 获取用户应用列表 * @apiVersion 1.0.0 * @apiGroup home * @apiName homeApps * @apiDescription * 获取apps 接口 * 需要登录之后才能访问 * * @apiUse defaultParam * * @apiUse sendSuccess * @apiSuccess {Aarray[]} data 数据 * @apiSuccess {Number} data.id 应用id * @apiSuccess {String} data.name 英文名称 * @apiSuccess {String} data.title 中文名称 * @apiSuccess {String} data.description 描述 * @apiSuccess {Number} data.status 状态 * @apiSuccess {String} data.author 作者 * @apiSuccess {String} data.version 版本号 * @apiSuccess {Number} data.create_time 创建时间戳 * @apiSuccess {Number} data.update_time 更新时间戳 * @apiSuccess {Number} data.auth 可见权限 0全部可用 1指定用户可用 2仅超级系统管理员可用 -1游客可用 * @apiSuccess {String} data.host_url 域名 * @apiSuccess {String} data.home_url 入口地址 * @apiSuccess {String} data.icon_url 图标地址 * * @apiSuccessExample {json} 返回样例 {"status":1,"request":"\/home\/api\/apps?platform=web","data":[{"id":2,"name":"department","title":"部门管理","description":"部门","status":1,"config":null,"author":null,"version":null,"create_time":1490063104,"update_time":1490063104,"auth":0,"type":1,"host_url":null,"home_url":"http:\/\/center.ys.test\/department\/department\/index.html","icon_url":"\/data\/apps\/department\/icon.png"},{"id":3,"name":"apps","title":"应用管理","description":"应用管理","status":1,"config":null,"author":null,"version":null,"create_time":1490063104,"update_time":1490063104,"auth":2,"type":1,"host_url":null,"home_url":"http:\/\/center.ys.test\/apps\/apps\/index.html","icon_url":"\/data\/apps\/apps\/icon.png"}]} * @apiUse sendError * @apiErrorExample {json} 返回样例 {"status":0,"request":"\/home\/api\/apps?platform=web","error":"您还没有登录过!","error_code":"10001"} */ /** * 这段不跟apidoc没关系 * @apiDefine用来定义 然后通过@apiUse sendError调用 */最后通过命令生成文档,如下,已设置环境变量可以直接打apidoc
apidoc -i D:\www\php\ysos\ys_center\application -o D:\www\php\ysos\ys_center\public\apidoc-i输入目录apidoc.json存放的目录 -o输出目录