翔奕时代

A year's plan starts with spring.

0%

ApiDoc开发文档使用简介

发表于 更新于 分类于 2.3k 2 分钟

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/