ApiDoc开发文档使用简介

apidoc是一款比较好用的开发文档生成工具,操作简单易理解,可以使用在C#、Go、Java、JavaScript、PHP等开发语言中。

安装

1、安装node.js(https://nodejs.org/zh-cn/)
2、安装iapDoc

1
npm install apidoc -g

配置

在项目根目录下新建apidoc.json文件,该文件描述了项目对外提供接口的概要信息,比如名称、描述、版本、文档打开时浏览器显示标题和接口缺省访问地址。
apidoc.json

1
2
3
4
5
6
7
{
"name": "knight.s.hongju.cc",
"version": "1.0.0",
"description": "knight公共服务api",
"title": "Custom apiDoc browser title",
"url" : ""
}

使用样例

在每个方法体的前面加入apidoc的注释批注,主要是对api开放出去的接口的请求方式、请求地址、版本、分组、授权、头部、成功/失败返回实例等的描述

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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
/**
* @api {get}/ekuaibao/get_invoices_specifications 获取企业单据模板列表
* @apiVersion 1.0.0
* @apiName 获取企业单据模板列表
* @apiGroup 易快报
* @apiSuccessExample Success-Response:
success: true,
code: 200,
msg: "获取成功",
data: [
{
id: "0qE9XeZa9Ysw00",
name: "申请单",
type: "requisition"
},
{
id: "25wa-UgKfohI00",
name: "测试-平台刷单费用报销单",
type: "expense"
},
{
id: "2lEb159L9AoI00",
name: "测试-赠送虚拟币收支申请",
type: "custom"
},
{
id: "59kau3TSLIfA00",
name: "福利费用报销单",
type: "expense"
},
{
id: "6FQb457wMwdY00",
name: "测试-平台费用红冲退回借款单",
type: "loan"
}
]
*/
/**
* - 获取企业单据模板列表
*
* @param Request $request
* @param Response $response
* @return Response
*/
public function getInvoicesSpecifications(Request $request, Response $response) : Response
{
.....
}

@api

1
@api {method} path [title]

HTTP接口调用方法、路径及名称

@apiVersion

1
@apiVersion version

api 版本号

@apiName

1
@apiName name

api 名称

@apiGroup

1
@apiGroup name

api 分组

@apiHeader

1
@apiHeader [(group)] [{type}] [field=defaultValue] [description]

请求头参数

@apiParam

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

请求参数

@apiSuccess

1
@apiSuccess [(group)] [{type}] field [description]

返回数据描述

@apiSuccessExample

1
2
@apiSuccessExample [{type}] [title]
example

接口成功返回样例

@apiError

1
@apiError [(group)] [{type}] field [description]

接口失败描述

@apiErrorExample

1
2
@apiErrorExample [{type}] [title]
example

接口失败返回样例

@apiDefine

1
2
@apiDefine name [title]
[description]

类似于宏定义,可以被引用

@apiUse

1
@apiUse name

使用@apiDefine定义的描述

更详细的说明请参考官方文档http://apidocjs.com

生成文档

cd到apidoc.json所在路径(即项目根目录)执行如下命令即可

1
apidoc -i src/ -o apidoc/

实际执行示例:

1
apidoc -i ~/data/htdocs/knight.s.hongju.cc/src -o ./api_docs

执行完毕后会在项目根目录下生成一个apidoc的文件夹,里面生成了apidoc显示对应的静态页面以及css、js文件等,直接访问apidoc下面的index.html就会看到已经生成好的非常漂亮的文档界面。

谢翔 wechat
坚持原创技术分享,您的支持将鼓励我继续创作!
-------------本文结束感谢您的阅读-------------
0%