ApiDoc接口文档工具

ApiDoc接口文档工具

  • 2018-11-26

ApiDoc

参考

前言

ApiDoc 用来比较规范的管理 API 文档。

ApiDoc 这个 API 文档管理器，可以根据你代码的注释来进行自动生成 API 文档。

同时支持 C#、Java、JavaScript、PHP、Python等语言。

目录

目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
project  项目目录
├─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.json

1
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用于对文档里面的接口分组，接口等进行排序

基本使用

安装
1
npm install apidoc -g
创建目录
1
$ mkdir src && mkdir output

创建配置文件 apidoc.json

1
$ touch 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：

1
$ touch 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
*/

当有多个@apiErrorExample时候，页面会以tab标签形式展示，方便我们返回多种异常样例

定义接口分组和权限

创建文件 define.php

1
$ touch define.php

define.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
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.md

1
$ touch header.md

header.md

1
2
3
4
5
产品需求说明：<a href="http://www.baidu.com" target="_blank">戳这里直达</a>  

作者 ：
  * chenchao
  * chenchao_cn@qq.com
接口文档编写

创建版本目录，默认为：v1

1
$ mkdir v1 && touch user.php

user.php

1
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

错误返回信息示例，以定义的代码格式输出，如 json

1
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
 */
感谢您的阅读，本文由 Double-c 版权所有。如若转载，请注明出处：Double-c（https://double-c.github.io/2018/11/26/api-doc/）
Git 配置多用户
你是怎么变自律？