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

1.特点:

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

2.安装前准备

  1. 安装node
  2. 安装node的npm
  3. 用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 <code>id</code> not found   
 * @apiError token     <code>token</code>   错误
 */
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

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

推荐阅读更多精彩内容