apidoc 生成Restful web Api文档

在项目开发过程中,总会牵扯到接口文档的设计与编写,之前使用的都是office工具,写一个文档,总也是不够漂亮和直观。好在git上的开源大神提供了生成文档的工具,so来介绍一下! 
该工具是Nodejs的模块,请务必在使用前安装好nodejs环境!

一.安装Apidoc

1.安装nmp环境,Windows环境可直接通过http://nodejs.org/下载安装包安装

2.安装后在cmd终端执行npm install apidoc –g如果执行失败跳到步骤3

3.安装npm首先先安装Homebrew在终端ruby -e "$(curl –fsSL

https://raw.githubusercontent.com/Homebrew/install/master/install)"

4.执行成功终端输入brew install node等待一段时间

5.执行成功终端输入npm –v确认是否npm安装成功

 

6.安装npm成功后执行执行npm install apidoc –g 安装apidoc即可。

二.apidoc使用

1.在项目根目录中创建apidoc.json文件

{
  "name": "Apidoc Example",
  "version": "1.0.0",
  "description": "Apidoc Example descrption",
  "title": "Custom apiDoc browser title",
  "url" : "http://localhost:8080/v1",
  "sampleUrl": "http://localhost:8080/v1",
  "forceLanguage":"zh-cn",
  "template": {
   "withCompare": true,
   "withGenerator": true
  }
}

2.在对应接口上加上注释:

示例:

/**
 *
 * @api {post} /m/login.do  登录
 * @apiName 登录
 * @apiGroup login
 * @apiVersion 1.0.0
 * @apiDescription 接口详细描述
 *
 * @apiParam {String} username 用户名
 * @apiParam {String} password 密码
 *
 * @apiSuccess {String} status 结果码
 * @apiSuccess {String} msg 消息说明
 * @apiSuccessExample Success-Response:
 *  HTTP/1.1 200 OK
 * {
 * status:0,
 * msg:'success',
 * data:{}
 *  }
 *
 *  @apiError All 对应<code>id</code>的用户没找到
 *  @apiErrorExample {json} Error-Response:
 *  HTTP/1.1 200
 *  {
 *   code:-1,
 *   msg:'user not found',
 *   }
 */

3.执行终端命令apidoc -i example/ -o doc/执行成功就则会在该目录下生成doc文件。

// 典型用法
apidoc -i api/ -o doc/api [-c ./] -f ".*\.js$"

-i 表示输入,后面是文件夹路径
-o 表示输出,后面是文件夹路径
默认会带上-c,在当前路径下寻找配置文件(apidoc.json),如果找不到则会在package.json中寻找 "apidoc": { }
-f 为文件过滤,后面是正则表达式,示例为只选着js文件
  与-f类似,还有一个 -e 的选项,表示要排除的文件/文件夹,也是使用正则表达式

示例:

apidoc -i e:\example -o e:\doc

这样就会在e:\doc目录下生成项目的doc文档,点开index.html就会看到如下效果

三.apidoc代码注释

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

详细文档参考http://caixw.oschina.io/apidoc/


  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值