Apidoc使用教程

2022-05-14 约 534 字预计阅读 2 分钟

配置

安装node.js
安装apidoc

1

npm install apidoc -g

在项目根目录下新建apidoc.json文件

1
2
3
4
5
6
7


{
  "name": "wxshop",
  "version": "1.0.0",
  "description": "小微店铺",
  "title": "小微店铺",
  "url" : "https://localhost:8080/api/v1"
}

使用样例

 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


/**
     * @api {post} /code 请求验证码
     * @apiName GetCode
     * @apiGroup 登录与鉴权
     *
     * @apiHeader {String} Accept application/json
     * @apiHeader {String} Content-Type application/json
     *
     * @apiParam {String} tel 手机号码
     * @apiParamExample {json} Request-Example:
     *          {
     *              "tel": "13012345678",
     *          }
     *
     * @apiSuccessExample Success-Response:
     *     HTTP/1.1 200 OK
     * @apiError 400 Bad Request 若用户的请求包含错误
     *
     * @apiErrorExample Error-Response:
     *     HTTP/1.1 400 Bad Request
     *     {
     *       "message": "Bad Request"
     *     }
     */
    /**
     * @param telAndCode 手机号和收到的验证码
     * @param response HTTP response
     */
    @PostMapping("/code")
    public void code(@RequestBody TelAndCode telAndCode,
                     HttpServletResponse response) {
        if (telVerificationService.verifyTelParameter(telAndCode)) {
            authService.sendVerificationCode(telAndCode.getTel());
        } else {
            response.setStatus(HttpStatus.BAD_REQUEST.value());
        }
    }

@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定义的描述

生成文档

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

1

apidoc -i src/ -o apidoc/

执行成功后会生成apidoc文件夹;
点开apidoc文件夹中index.html会发现已经生成的漂亮的api文档。