Web API文档生成工具apidoc安装与使用

apidoc可以根据代码注释生成web api文档，支持大部分主流语言java javascript php coffeescript erlang perl python ruby go...，相对而言，web接口的注释维护起来更加方便，不需要额外再维护一份文档。

apidoc从注释生成静态html网页文档，不仅支持项目版本号，还支持api版本号。

安装

主页: http://apidocjs.com

github: https://github.com/apidoc/apidoc

可以使用npm install apidoc -g进行安装，目前0.12.x/4.0都可以使用。

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输出目录

Web API文档生成工具apidoc安装与使用

猜你喜欢