apidocjs-开发人员最好用的API文档

1.特点：

apidoc是根据你源代码中的API注释生成的文档，一行命令即可生成api接口文档
此api文档集成了各个版本API，清晰的显示了各个版本之间的对比
可随意查看不同版本的api
拥有强大的接口测试功能，只要填写参数，即可查看响应数据

2.安装前准备

安装node
安装node的npm
用npm安装apidoc
npm install apidoc -g

3.使用教程

前提是你的源码中已经编写了api的接口注释
apidoc -i yourProjectFile -o apidoc
yourProjectFile 你自己的项目文件夹

apidoc生成的web形式的api文档
文档入口apidoc/index.html

（以下demo主要以java代码来演示，其他语言也给了出示例）

3.1 项目中如何编写接口注释

java注释

/** 
* 这部分写接口注释内容（完整的注释模板在本文结尾给出）
*/

CoffeeScript 注释

###
 这部分写接口注释内容（完整的注释模板在本文结尾给出）
###

Elixir

@apidoc """
 这部分写接口注释内容（完整的注释模板在本文结尾给出）
"""

Erlang (% within the comment is optional)注释

%{
%  这部分写接口注释内容（完整的注释模板在本文结尾给出）
%}

Perl (Oxygen)注释

#**
#  这部分写接口注释内容（完整的注释模板在本文结尾给出）
#*

Python注释

"""
 这部分写接口注释内容（完整的注释模板在本文结尾给出）
"""

Ruby注释

=begin
 这部分写接口注释内容（完整的注释模板在本文结尾给出）
=end

3.2 项目中可以通过配置，来设置注释的模板，java中代码的注释如下

/** 
  * @api {get} /user/:id Get User information and Date of Registration. 
  * @apiVersion 0.2.0 
  * @apiName GetUser
  * @apiGroup User  
  * 
  * @apiParam {Number} id Users unique ID.
  * 
  * @apiSuccess {String} firstname Firstname of the User. 
  * @apiSuccess {String} lastname Lastname of the User.  
  * @apiSuccess {Date} registered Date of Registration. 
  * 
  * @apiSuccessExample Success-Response: 
  * HTTP/1.1 200 OK 
  *  {
  * "firstname": "John", 
  * "lastname": "Doe" 
  * } 
  * 
  * @apiError UserNotFound The id of the User was not found. 
  * 
  * @apiErrorExample Error-Response: 
  * HTTP/1.1 404 Not Found 
  * {
  * "error": "UserNotFound"
  * } 
  */

3.3下面逐一解释上面的属性

3.3.1 @apidoc

@api {method} path [title]

名称	含义
method	请求方法的名称DELETE, GET, POST, PUT
path	请求的路径
title	api名称，会在导航栏中显示

3.3.2 @apiDefine 自定义api属性模板

格式：`@apiDefine name [title] [description]
下面的例子是自定义的@apiError 当然你可以自定义其他属性@apiPermission ，@apiSuccess或者其他属性，如下一次定义，不同api都可以引用，
引用方式 * @apiUse UserNotFoundError
Example:

/**
 * @apiDefine UserNotFoundError
 *
 * @apiError UserNotFound The id of the User was not found.
 *
 * @apiErrorExample Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

/**
  * @api {get} /user/:id Request User information
  * @apiName GetUser
  * @apiGroup User
  *
  * @apiParam {Number} id Users unique ID.
  *
  * @apiSuccess {String} firstname Firstname of the User.
  * @apiSuccess {String} lastname  Lastname of the User.
  *
  * @apiSuccessExample Success-Response:
  *     HTTP/1.1 200 OK
  *     {
  *       "firstname": "John",
  *       "lastname": "Doe"
  *     }
  *
  * @apiUse UserNotFoundError
  */

 /**
  * @api {put} /user/ Modify User information
  * @apiName PutUser
  * @apiGroup User
  *
  * @apiParam {Number} id          Users unique ID.
  * @apiParam {String} [firstname] Firstname of the User.
  * @apiParam {String} [lastname]  Lastname of the User.
  *
  * @apiSuccessExample Success-Response:
  *     HTTP/1.1 200 OK
  *
  * @apiUse UserNotFoundError
  */

3.3.3 @ apiVersion

一个项目可能有不同的版本，对应的API可能也有不同的版本，添加这个属性就可以根据版本来选择对应的API了，
！！！代码中的一个注释对应一个api接口，例如：login接口在源码中的注释有两个，版本分别是
@ apiVersion =0.2.0
@ apiVersion =0.2.1
那么生成的api文档才会有两个版本的对比，如果源码中只有一个版本login的注释，那么API文档中也只有一个接口显示，就没有版本对比

下图是API两个版本的对比。
相对于0.2.0的版本新增了fileAdd字段是绿色。
删除了firstName标注成了红色

0.2.1相对与0.2.0版本API的差异

3.3.4 @apiName name 接口名

但是在html格式的文档中不会显示，导航栏中的接口标题是在@apidoc属性中设置的
Example：

/**
 * @api {get} /user/:id 
 * @apiName GetUser
 */

3.3.4 @apiGroup API接口的分组，例如登录api和获取用户信息api都是用户模块

Example：

/**
 * @api {get} /user/:id 
 * @apiGroup User
 */

3.3.5 apiDescription 接口描述

@apiDescription text
Example：

/**
 *  @apiDescription 这个接口是用来获取用户信息的（这是关于接口的描述内容）
 */

3.3.6 @apiParam API的请求参数

@apiParam [(group)] [{type}] [field=defaultValue] [description]

名称	含义
group （可选）	请求方法的名称DELETE, GET, POST, PUT
{type} （可选）	参数类型{Boolean}, {Number}, {String}, {Object}, {String[]}，(array of strings)
{type{size}} （可选）	变量的范围 {string{..5}}这个字符串最多5个字符 {string{2..5}}这个字符串最少2个字符，最多5个字符 {number{100-999}} 在100到999之间的数字
{type=allowedValues}(可选)	参数的可选值 {number=1,2,3,99} 这个数字的值只能是其中之一 {string="small","huge"} 这个字符串的值只能是small或者huge {number=1,2,3,99} 这个数字的值只能是其中之一
field	字段名
defaultValue	字段的默认值
description	字段的描述（这个字段的含义）

3.3.7 @apiParamExample 请求参数示例

这个是参数的具体请求格式的一个例子，主要针对json类型的数据,格式如下
@apiParamExample [{type}] [title] example

/** 
 * @api {get} /user/:id 
 * @apiParamExample {json} Request-Example:
 *  {
 *    "id": 4711 
 *  } 
 */

3.3.8 @apiError api 请求出错返回字段说明

格式：@apiError [(group)] [{type}] field [description]
Example：

/** 
 * @api {get} /user/:id 
 * @apiError UserNotFound   The id not found   
 * @apiError token     token   错误
 */

3.3.9 @apiErrorExample Error-Response: api请求错误返回数据示例

格式：@apiErrorExample [{type}] [title] example
请求失败返回的数据(json格式)
Example：

/** 
* @api {get} /user/:id 
* @apiErrorExample {json} Error-Response: 
* HTTP/1.1 404 Not Found
 * {
 * "error": "UserNotFound" 
* }
 */

类似的 @apiSuccess 是请求成功以后的字段含义说明

@apiSuccessExample 是请求成功后的响应数据

用法一致，只是名字不同

3.3.10 @apiSampleRequest 接口请求示例

这个功能可谓这个文档中一个强大的功能,如下

Example:

 * @apiParam {String} token  搜索内容
 * @apiSampleRequest   http://your_api_url

设置了参数以及url生成的html中即可看到效果

@apiSampleRequest属性使用

3.3.10 @apiIgnore 隐藏api

格式： @apiIgnore [hint]
这个属性用于开发人员还没有完全编写好的接口，如果不想显示在html文档中那么就使用这个属性
Example:

/** 
 * @apiIgnore 这个接口暂时还没有开发完，暂时不显示
 * @api {get} /user/:id
  */

3.3.11 @apiHeader

HTTP Header中Accept-Encoding 是浏览器发给服务器,声明浏览器支持的编码类型
格式：@apiHeader [(group)] [{type}] [field=defaultValue] [description]
Example:

/** 
 * @api {get} /user/:id 
 * @apiHeader {String} access-key Users unique access-key.
  */

3.3.12 @apiHeaderExample

@apiHeaderExample [{type}] [title] example

/**
  * @api {get} /user/:id  
 * @apiHeaderExample {json} Header-Example: 
 * { 
 * "Accept-Encoding": "Accept-Encoding: gzip, deflate"  
 * } 
 */

3.3.13 @apiUse 重用的文本模块

@apiUse name

/**
 * @apiDefine MySuccess
 * @apiSuccess {string} firstname The users firstname.
 * @apiSuccess {number} age The users age.
 */

/**
 * @api {get} /user/:id
 * @apiUse MySuccess
 */

demo

http://download.csdn.net/detail/xubeiqiannian/9563098

更多请参照官方文档 http://apidocjs.com/#param-api-use、

有待完善，暂时就整理这些吧