apidoc使用教程-很好用的一款读取注释生成文档工具

一.apidoc说明

1.如何安装

前提：确保已安装node.js 使用npm进行apidoc安装  
node.js下载

npm install apidoc -g

2.如何使用

1)建立配置文件

分两种情况：

①已经有package.json文件

{ 
  "name": "文档名称", 
  "version": "0.1.0", 
  "description": "文档描述", 
  "apidoc": { 
      "title": "这是网页显示的title", 
      "url" : "API基础URL" 
  }
}

②没有package.json文件

在根目录创建apidoc.json文件并写入:

{ 
  "name": "文档名称", 
  "version": "0.1.0", 
  "description": "文档描述",
  "title": "这是网页显示的title", 
  "url" : "API基础URL"
}

2)写代码注释
常用的标签注释：


@apiDefine 用于定义变量，可以用于使@apiGrounp支持显示中文

格式：

/**
 * @apiDefine key value
 * key:变量名   value：变量值
 */

例子：

/**
 * @apiDefine userApiStr 用户接口文档 
 */

@api 一般是必须编写的，不然apidoc编译器会忽略这段注释。

格式：

/** 
 * @api{method} path name
 * method:请求方法名   path:Uri  name:API名称  
 */

例子：

/** 
 * @api {get} /login 用户登录
 */

@apiGroup 定义API所属组名称，用于页面分类展示，支持变量或者ascll码


格式：

/** 
 * @apiGroup  name
 * name:组名称
 */

例子：

/** 
 * @apiGroup loginApi
 */

@apiName 用于定义API文档的一个实例，并用作实例名称

格式：

/** 
 * @apiName  name
 * name:api名称
 */

例子：

/** 
 * @apiName 登录接口
 */

@apiParam 接口参数
格式：

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

name	Description
(group) 可选	参数归属组名，不填写组名，则默认设为Paramter
{type} 可选	参数数据类型，如{String}、{Number}、{Array}等等
{type{size}} 可选	变量的大小信息 {String{…5}}参数类型为一个字符不超过5的字符串；{String{2…5}}参数为一个字符在2到5之间的字符串；
type=allowedValues} 可选	参数允许值 {string=“small”,“huge”}参数只能接受small或者huge的字符串
field 可选	参数名称
=defaultValue	参数默认值
description 可选	描述

例子：

/** 
 * @apiParam {String} password 密码
 */

@apiSuccess 返回成功数据描述

格式：

/** 
 * @apiSuccess [(group)] [{type}] field [description] 
 * group:分组组名(默认设为Success 200) type:字段类型  field:字段  description:描述
 */

例子：

/** 
 * @apiSuccess (200) {String} msg  返回信息
 * @apiSuccess (200) {String} code 0 代表无错误 1代表有错误
 */

@apiSuccessExample 请求成功返回的字段参数例子

格式：

/**
 * @apiSuccessExample [{type}] [title] example
 * type:类型  title：例子名称  example:样例
 */

例子：

/**
 * @apiSuccessExample {json} 返回样例:
 * {"code":"0","msg":"登录成功","userId":"fe6386d550bd434b8cd994b58c3f8075"}
 */

@apiError & @apiErrorExample

这两个的用法跟 @apiSuccess、@apiSuccessExample的用法相类似。

@apiIgnore 用来忽视该注释块，将其放在注释块顶部
格式：

/**
 * @apiIgnore tips
 * tips:简要说明忽视原因
 */

例子:

/**
 * @apiIgnore not finished 
 */

一个简单的完整例子：

<?php
	class Test
	{
		/**
 		 * @apiDefine userApiStr 用户接口文档 
 		 */
		
		/**
		 * @api {POST} /login 用户登录
		 * @apiName api测试
		 * @apiGroup userApiStr
		 * @apiVersion 1.0.0
		 * @apiDescription 用于用户登录
		 * @apiParam {String} userName 用户名
		 * @apiParam {String} password 密码
		 * @apiParamExample {json} 请求样例：
		 *                ?userName=张三&password=11223344
		 * @apiSuccess (200) {String} msg 信息
		 * @apiSuccess (200) {String} code 0 代表无错误 1代表有错误
		 * @apiSuccess (200) {String} user 用户信息
		 * @apiSuccess (200) {String} userId 用户id
		 * @apiSuccessExample {json} 返回样例:
		 *                {"code":"0","msg":"登录成功","userId":"fe6386d550bd434b8cd994b58c3f8075"}
		 */

		public function test()
		{

		}
	}

---

3.如何生成

在含有配置文件的目录下，使用DOS命令：

apidoc -i 源代码目录 -o 输出文档目录

例子：

apidoc -i src/ -o apidocs/

该命令将会读取所在目录下的src目录所有注释，并生成文档页面到所在目录的apidocs目录下。

浏览器打开index.html即可。


显示效果图示：

点击这里查看网页效果