php api文档模板doc,ApiDoc接口文档工具
ApiDoc
参考
前言
ApiDoc 用来比较规范的管理 API 文档。
ApiDoc 这个 API 文档管理器，可以根据你代码的注释来进行自动生成 API 文档。同时支持 C#、Java、JavaScript、PHP、Python等语言。
目录
目录结构1
2
3
4
5
6
7
8
9
10
11
12
13project 项目目录
├─src 源代码目录
│ ├─commom.php 定义权限，状态码，错误响应等
│ ├─define.php 定义接口分组
│ ├─header.md 页首内容
│ ├─footer.md 页尾内容
│ ├─history.php 历史版本，只存放小版本更新
│ ├─v1 版本目录
│ │ ├─ ...... 详细的接口文件
├─output 编译后存放目录
│ ├─......
│ ├─index.html 编译后的静态首页
├─apidoc.json 配置文件示例的所有目录文件都需要自己去创建
结构仅供参考， ApiDoc 并不强制要求。
常用命令
apidoc -xxx-i：指定源代码目录
-o：指定输出目录
-t：指定模板输出文件
-f：解析的文件apidoc -f ".*\.js$" ：只解析 .js 文件
配置
ApiDoc 配置是基于项目根目录的 apidoc.json 中设置的
apidoc.json1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16{
"name":"example",
"version":"0.1.0",
"description":"apiDoc basic example",
"title":"Custom apiDoc browser title",
"url":"https://api.my-project.com/v1",
"sampleUrl":"https://api.my-develop.com/v1",
"header":{
"title":"项目概要",
"filename":"header.md"
},
"order":[
"userGroup",
"orderGroup"
]
}
配置项说明名称描述name项目名称
version项目版本
description项目描述
title浏览器上的 title 名称
url接口地址
sampleUrl接口测试地址
header.title左侧导航标签头部内容的标题
header.filename相对于源代码目录的头部文件路径，文件内容使用markdow语法
footer.title左侧导航标签底部内容的标题
footer.filename相对于源代码目录的底部文件路径，文件内容使用markdow语法
order用于对文档里面的接口分组，接口等进行排序
基本使用
安装1npm install apidoc -g
创建目录1mkdir src && mkdir output
创建配置文件 apidoc.json1touch apidoc.json
apidoc.json：1
2
3
4
5
6
7
8
9
10
11{
"name": "apidoc-study",
"version": "1.0.0",
"title": "apidoc 学习",
"url": "http://apidoc.com/v1",
"description": "apiDoc 示例",
"header": {
"filename": "header.md",
"title": "项目概要"
}
}
定义错误响应
创建文件 common.php：1touch common.php
common.php：1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25<?php
*错误响应(apiError、apiErrorExample)
*/
*@apiDefine CommonError
*
* @apiError (客户端错误) 400-BadRequest 请求信息有误，服务器不能或不会处理该请求
* @apiError (服务端错误) 500-ServerError 服务器遇到了一个未曾预料的状况，导致了它无法完成对请求的处理。
* @apiErrorExample {json} BadRequest
*HTTP/1.1 401 BadRequest
*{
*"message": "请求信息有误",
*"code": 400,
*"data":[]
*}
* @apiErrorExample {json} ServerError
*HTTP/1.1 500 Internal Server Error
*{
*"message": "系统错误，请稍后再试",
*"code": 500,
*"data":[]
*}
*/
如何使用自定义的错误响应：1
2
3* @apiUse CommonError // 该使用common.php 定义的错误信息返回文档块 CommonError
*/[email protected]，页面会以tab标签形式展示，方便我们返回多种异常样例
定义接口分组和权限
创建文件 define.php1touch define.php
define.php1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28<?php
* api分组(Group)
*/
*@apiDefine userGroup 用户相关
*用户列表，信息修改等
*/
*@apiDefine dataGroup 数据相关
* 相关数据的增删改查
*/
* 权限(apiPermission)
*/
*@apiDefine token 需要用户授权
* 详情查看用户授权接口
*/
*@apiDefine none 无需授权
*该接口没有权限限制
*/
如何使用定义的权限组：1
2
3
4
5
6
7* @apiGroup userGroup // 该使用define.php 定义的接口分组 userGroup
*/
/**
* @apiPermission none // 该使用define.php 定义的权限 none
*/
定义页首
创建文件 header.md1touch header.md
header.md1
2
3
4
5产品需求说明：戳这里直达
作者 ：
* chenchao
接口文档编写
创建版本目录，默认为：v11$ mkdir v1 && touch user.php
user.php1
2
3
4
5
6
7
8
9/**
*@api {post} /users/:id 更新用户信息
* @apiName update-user
* @apiVersion 1.0.0
* @apiGroup userGroup
* @apiPermission none
*
* @apiUse CommonError
*/
执行命令：1$ apidoc -i src/ -o output
执行成功时显示：1{"message":"Done.","level":"info"}
常用参数
@api
必须值，如果没有该参数，解析器将忽略该文档块。1@api {method} path [title]
参数说明：名称说明是否必须method请求方法，例：GET 、POST、DELETE 等等。是
path请求路径是
title简短的标题，用于左侧导航和接口标题否
示例：1
2
3/**
* @api {get} /user/:id
*/
@apiDefine
定义要嵌入 @api 的文档块或 api function 里的文档块。
@apiDefine 定义的在每个块里只能使用一次。1
2@apiDefine name [title]
[description]
参数说明：名称说明是否必须name块的唯一名称，如果使用相同名称可以使用不同版本 @apiVersion 去定义是
title一个简短的标题，仅用于命名函数，如：@apiPermission 或 @apiParam(name)否
description详细说明从下一行开始，可以使用多行。仅用于命名函数 @apiPermission否
示例：1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26/**
* @apiDefine UserNotFoundError
*
* @apiError UserNotFound The id of the User was not found.
*
* @apiErrorExample Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
/**
* @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
*/
@apiDeprecated
将 API 方法标记为已弃用1@apiDeprecated [text]
参数说明：名称描述是否必须text多行文字是
@apiDescription
API 方法的详细描述
参数说明：名称描述是否必须text多行文字是
@apiError
错误返回参数1@apiError [(group)] [{type}] field [description]
参数说明：名称描述是否必须( group )所有参数都将按此名称分组，否
{ type }返回类型，如：{Boolean}、{Number}、{String}、{Object}否
field错误类型是
description错误描述否
@apiErrorExample
错误返回信息示例，以定义的代码格式输出，如 json1
2@apiErrorExample [{type}] [title]
example
参数说明：名称描述是否必须{type}返回格式，如 {json}可选
title描述标题可选
example
示例：1
2
3
4
5
6
7
8/**
* @api {get} /user/:id
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 404 Not Found
* {
* "error": "UserNotFound"
* }
*/
@apiExample
API 方法的使用示例1
2@apiExample [{type}] title
example
参数说明：名称描述是否必须{type}代码语言否
title标题是
example示例是
示例：1
2
3
4
5/**
* @api {get} /user/:id
* @apiExample {curl} Example usage:
* curl -i http://localhost/user/4711
*/
@apiGroup
推荐经常使用。
定义方法，文档块属于哪个分组。分组名称将用于主导航。1@apiGroup name
参数说明：名称描述是否必须name分组名称，也用于导航标题是
示例：1
2
3
4/**
* @api {get} /user/:id
* @apiGroup User
*/
@apiHeader
描述需要传给 API 的头部的参数，常用于授权。1@apiHeader [(group)] [{type}] [field=defaultValue] [description]
参数说明：名称描述是否必须( group )所属分组否
{ type }参数类型，可选：Boolen、Number、String否
field=defaultValue字段名，可设置默认值，默认值非必须是
description描述否
示例：1
2
3
4/**
* @api {get} /user/:id
* @apiHeader {String} access-key Users unique access-key.
*/
@apiHeaderExample
参数请求示例。1
2@apiHeaderExample [{type}] [title]
example
参数说明：名称描述是否必须{ type }请求格式否
title标题否
example示例是
示例：1
2
3
4
5
6
7/**
* @api {get} /user/:id
* @apiHeaderExample {json} Header-Example:
* {
* "Accept-Encoding": "Accept-Encoding: gzip, deflate"
* }
*/
@apilgnore
必须放在块的顶部。
@apilgnore 将使 ApiDoc 无法解析块。常用于过时的方法或未完成的方法里。
参数说明：名称描述是否必须hint描述为什么忽略这个块否
示例：1
2
3
4/**
* @apiIgnore Not finished Method
* @api {get} /user/:id
*/
@apiName
推荐经常使用。
定义接口名称，名称将用于导航中的子标题。1@apiName name
参数说明：名称描述是否必须名称方法的唯一名称，相同名称的方法应该使用不同的版本区分开来是
示例:1
2
3
4/**
* @api {get} /user/:id
* @apiName GetUser
*/
@apiParam
描述传递给 API 方法的参数。1@apiParam [(group)] [{type}] [field=defaultValue] [description]字段名中间加上 [ ] 表示该参数可选，非必填
示例：1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16/**
* @api {get} /user/:id
* @apiParam {Number} id Users unique ID.
*/
/**
* @api {post} /user/
* @apiParam {String} [firstname] Optional Firstname of the User.
* @apiParam {String} lastname Mandatory Lastname.
* @apiParam {String} country="DE" Mandatory with default value "DE".
* @apiParam {Number} [age=18] Optional Age with default 18.
*
* @apiParam (Login) {String} pass Only logged in users can post this.
* In generated documentation a separate
* "Login" Block will be generated.
*/
@apiParamExample
参数请求格式示例。1
2@apiParamExample [{type}] [title]
example
参数说明：名称描述是否必须{ type }请求格式否
title该示例的简称否
example详细的示例是
例：1
2
3
4
5
6
7/**
* @api {get} /user/:id
* @apiParamExample {json} Request-Example:
* {
* "id": 4711
* }
*/
@apiPermission
该接口所需的权限名称。1@apiPermission name
参数说明：名称描述是否必须name权限的 唯一 名称是
@apiPrivate
将 Api 定义为私有，以允许创建两个 API 规范文档，一个排除私有接口，一个包含私有接口。
用于排除 / 包含 私有 Api 的命令行： --private false|true
示例：1
2
3
4/**
* @api {get} /user/:id
* @apiPrivate
*/
@apiSuccess
成功请求返回参数。1@apiSuccess [(group)] [{type}] field [description]
参数说明：名称描述是否必须( group )组否
{ type }返回类型否
field字段是
description描述否
示例：1
2
3
4
5
6
7/**
* @api {get} /user/:id
* @apiSuccess {Boolean} active Specify if the account is active.
* @apiSuccess {Object} profile User profile information.
* @apiSuccess {Number} profile.age Users age.
* @apiSuccess {String} profile.image Avatar-Image.
*/
@apiSuccessExample
成功返回示例。1
2@apiSuccessExample [{type}] [title]
example
参数说明：名称描述是否必须{ type }类型否
title标题否
example示例是
@apiUse
引入一个已定义的块。1@apiUse name
参数说明：名称描述是否必须name块名称是
示例：1
2
3
4
5
6
7
8
9
10/**
* @apiDefine MySuccess
* @apiSuccess {string} firstname The users firstname.
* @apiSuccess {number} age The users age.
*/
/**
* @api {get} /user/:id
* @apiUse MySuccess
*/
@apiVersion
设置文档块的版本，也可用于 @apiDefine。1@apiVersion version
参数说明：名称描述是否必须version版本号是
示例：1
2
3
4/**
* @api {get} /user/:id
* @apiVersion 1.6.2
*/