php apidoc 注释,apiDoc从代码docblock生成api文档
官网手册：
第1章前言
1.1注释风格
使用Javadoc-Style(可用于C＃，Go，Dart，Java，JavaScript，PHP，TypeScript和所有其他具有Javadoc功能的语言)：
/**
* 这里全是注释。。。。。
*/
下面是个更多内容的注释
/**
* @api {get} /user/:id 用户信息
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*/
另外还支持以下语言(代码注释不同于Javadoc-Style)CoffeeScript、Elixir、Erlang、Perl、Python、Ruby、Lua
第2章安装
2.1npm安装
apt-get install nodejs
apt-get install npm
npm config set registry
npm install apidoc -g
或
cnpm install apidoc -g
2.2运行
使用命令：
apidoc -i myapp/ -o apidoc/ [ -t mytemplate/ ] [ -f ".*\.php$" ]
执行结果：
info: Done.
info: Nothing to do.
2.3配置ApiDoc.json
name
Description
name
API的项目名，不设置将由apidoc自动生成
version
项目的版本号
description
项目的描述
title
浏览器的title
url
docBlock中@api的path前缀
sampleUrl
如果设置该值，将在所有的接口中生成一个测试表单，可以配合docBlock中@apiSampleRequest标签使用
header
title
被引入文件(header.md)的导航标题
filename
被引入文件(header.md)的文件名markdown-file
footer
title
被引入文件(footer.md)的导航标题
filename
被引入文件(footer.md)的文件名markdown-file
order
api的name列表或者group列表，对输出进行排序，未列出的部分顺序自动决定
2.4apiDoc-Params
Param
Description
Option
@api
定义api的请求方法和路径
必选
@apiDefine
定义嵌入到@api块内的docBlock
可选
@apiDeprecated
将API标记为不推荐使用
可选
@apiDescription
API方法的详细描述。
可选
@apiError
错误返回的参数定义
可选
@apiErrorExample
错误返回的消息示例，预格式化代码输出。
可选
@apiExample
调用API的示例。作为预格式化代码输出。
可选
@apiGroup
定义docBlock所属的组
常用
@apiHeader
描述API header头参数，例如授权信息。
可选
@apiHeaderExample
API请求头的参数示例
可选
@apiIgnore
(放在docBlock顶部)该标签定义的docBlock不被解析，例如接口未完成时不想发布
可选
@apiName
定义docBlock的名字，用于子导航
常用
@apiParam
描述接口参数
可选
@apiParamExample
请求参数示例
可选
@apiPermission
接口的访问权限定义
可选
@apiPrivate
将API定义为私有，以允许创建两个API规范文档
可选
@apiSampleRequest
生成一个测试用的form表单，如果该参数为路径时可以与apidoc.json中的sampleUrl配合使用
可选
@apiSuccess
成功返回时的参数描述
可选
@apiSuccessExample
成功返回消息的示例，作为预格式化代码输出。
可选
@apiUse
引用@apiDefine定义的docBlock
可选
@apiVersion
docBlock的版本号
可选
第3章Params使用
3.1 @api △
必选！！！
不给该参数，docBlock将被apiDoc解析器忽略。
但由@apiDefine定义的docBlock例外，不是必需的。
用法：@api {method} path [title]
示例：
/**
* @api {get} /user/:id 获取用户信息
*/
这里如果不给title导航中会没有的，还是给出吧
3.2 @apiDefine √
定义被@api块引入的docBlock，每个docBlock只能引入一次，通过使用@apiUse导入，title和description可能被一起引入。
用法：@apiDefine name [title]
[description]
示例：
/**
* @apiDefine MyError
* @apiError UserNotFound The id of the User was not found.
*/
/**
* @api {get} /user/:id
* @apiUse MyError
*/
3.3 @apiDeprecated
将API标记为不推荐使用
用法：@apiDeprecated use now (#Group:Name).
提示：可以描述文本可以多行
示例：
/**
* @apiDeprecated
*/
/**
* @apiDeprecated use now (#Group:Name).
*
* Example: to set a link to the GetDetails method of your group User
* write (#User:GetDetails)
*/
3.4 @apiDescription △
API的详细描述，可以多行
用法：@apiDescription This is the Description.
示例：
/**
* @apiDescription This is the Description.
* It is multiline capable.
*
* Last line of Description.
*/
3.5 @apiError √
错误返回的参数。
Usage: @apiError UserNotFound
示例：
/**
* @api {get} /user/:id
* @apiError UserNotFound The id of the User was not found.
*/
3.6 @apiErrorExample √
错误返回消息的示例，预格式化代码输出。
用法： @apiErrorExample {json} Error-Response:
This is an example.
示例：
/**
* @api {get} /user/:id
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
3.7 @apiExample
调用API的示例。预格式化代码输出。
用法： @apiExample {js} Example usage:
This is an example.
示例：
/**
* @api {get} /user/:id
* @apiExample {curl} 调用示例:
* curl -i
*/
3.8 @apiGroup △
很常用！！！
定义API所属的组。组将用于文档主导航。
用法： @apiGroup User
例：
/**
* @api {get} /user/:id
* @apiGroup User
*/
3.9 @apiHeader
对API header头参数的描述，例如授权参数信息
用法： @apiHeader (MyHeaderGroup) {String} authorization Authorization value.
例子：
/**
* @api {get} /user/:id
* @apiHeader {String} access-key Users unique access-key.
*/
3.10 @apiHeaderExample
API header参数请求示例。
用法： @apiHeaderExample {json} Request-Example:
{ "content": "This is an example content" }
例：
/**
* @api {get} /user/:id
* @apiHeaderExample {json} Header-Example:
* {
* "Accept-Encoding": "Accept-Encoding: gzip, deflate"
* }
*/
3.11 @apiIgnore
将其放在docBlock的顶部。
@apiIgnore定义的docBlock不会被解析，未完成不想发布的接口用它
用法： @apiIgnore Not finished Method
例：
/**
* @apiIgnore Not finished Method
* @api {get} /user/:id
*/
3.12 @apiName △
很常用！！！
定义docBlock的名字，用于子导航
用法： @apiName GetUser
例：
/**
* @api {get} /user/:id
* @apiName GetUser
*/
3.13 @apiParam △
描述API调用时的参数
用法： @apiParam (MyGroup) {Number} id 用户唯一id.
例子：
/**
* @api {get} /user/:id
* @apiParam {Number} id Users unique ID.
*/
3.14 @apiParamExample
请求API的参数示例。
用法： @apiParamExample {json} Request-Example:
{ "content": "This is an example content" }
例：
/**
* @api {get} /user/:id
* @apiParamExample {json} Request-Example:
* {
* "id": 4711
* }
*/
3.15 @apiPermission
输出API访问需要的权限名称
用法： @apiPermission admin
例：
/**
* @api {get} /user/:id
* @apiPermission none
*/
3.16 @apiPrivate
将API定义为私有，以允许创建两套API规范文档：排除私有API和包含私有API
用法： @apiPrivate
排除/包含私有API的命令行用法： --private false|true
例：
/**
* @api {get} /user/:id
* @apiPrivate
*/
3.17@apiSampleRequest
将此参数与apidoc.json配置参数sampleUrl配合使用。
如果sampleUrl设置，所有方法将具有api测试表单。
没有sampleUrl只有方法@apiSampleRequest，会有一个表单。
如果设置@apiSampleRequest url，则此url将用于测试表单的请求(当以http开头时，该url将覆盖sampleUrl)。
如果sampleUrl设置了，并且您不想使用测试表单的方法，则添加@apiSampleRequest off到文档块。
用法： @apiSampleRequest
例子：
/**
* @api {get} /user/:id
* @apiSampleRequest
*/
3.18@apiSuccess △
成功返回参数。
用法： @apiSuccess {String} firstname Firstname of the User.
例：
/**
* @api {get} /user/:id
* @apiSuccess {String} firstname Firstname of the User.
* @apiSuccess {String} lastname Lastname of the User.
*/
3.19@apiSuccessExample △
成功返回消息的示例，作为预格式化代码输出。
用法： @apiSuccessExample {json} Success-Response:
{ "content": "This is an example content" }
例：
/**
* @api {get} /user/:id
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* "firstname": "John",
* "lastname": "Doe"
* }
*/
3.20@apiUse √
包含一个@apiDefine定义的docBlock
用法： @apiUse MySuccess
例：
/**
* @apiDefine MySuccess
* @apiSuccess {string} firstname The users firstname.
* @apiSuccess {number} age The users age.
*/
/**
* @api {get} /user/:id
* @apiUse MySuccess
*/
3.21@apiVersion △
设置docBlock的版本。也可以用在@apiDefine的docBlock。
具有相同group和name的docBlock，但version不同，生成的文档可以对比差异
用法： @apiVersion 1.6.2
例：
/**
* @api {get} /user/:id
* @apiVersion 1.6.2
*/