安装

1
npm install -g apidoc

配置

  1. 新建 apidoc.json文件

    在源目录下新建 apidoc.json文件，该文件中为项目概要信息如名称、版本、描述、文档打开时浏览器显示标题和接口缺省访问地址

1
2
3
4
5
6
7
8
9
10
11
{
  "name": "License接口API",
  "version": "0.2.1",
  "description": "v0.2.1 系统软件许可证书 -- 接口文档",
  "title": "系统软件许可证书API",
  "url" : "http://127.0.0.1:8080",
  "template": {
  	"withCompare": true,
  	"withGenerator": true
  }
}

  1. 使用样例 - service.java

    在源目录下新建 service.java 文件

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
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
/**
 * @api {DESC}  证书认证模块使用说明
 * @apiName 证书认证模块使用说明
 * @apiGroup 1.License（描述）
 * @apiDescription License认证模块使用说明
 * @apiParamExample {text}说明:
   使用证书验证，需要增加license-verify-spring-boot-starter模块依赖，在需要证书验证的接口上
   增加@VLicense注解，模块系统中需要增加相应的证书配置，验证模块中需要放公钥和证书文件
 */
 
/**
 * @api {DESC}  App测试说明
 * @apiName App测试说明
 * @apiGroup 1.License（描述）
 * @apiDescription License组件App测试说明
 * @apiParamExample {html} 说明:
 
- > ### 测试证书生成（Creator）

配置文件启用creator模式配置且pom.xml文件引入license-creator-spring-boot-starter包

spring.profiles.active = creator

<dependency>
    <groupId>com.appleyk.spring.boot</groupId>
    <artifactId>license-creator-spring-boot-starter</artifactId>
    <version>0.2.1-SNAPSHOT</version>
</dependency>

详细配置请查看application-creator.properties文件


- > ### 测试证书验证（Verify）

配置文件启用creator模式配置且pom.xml文件引入license-verify-spring-boot-starter包

spring.profiles.active = verify

<dependency>
    <groupId>com.appleyk.spring.boot</groupId>
    <artifactId>license-verify-spring-boot-starter</artifactId>
    <version>0.2.1-SNAPSHOT</version>
</dependency>

详细配置请查看application-verify.properties文件
  
*/ 
 
 
/**
 * @api {DESC}  自定义属性验证使用说明
 * @apiName 自定义属性验证使用说明
 * @apiGroup 1.License（描述）
 * @apiDescription License组件自定义属性验证说明
 * @apiParamExample {html} 说明:
  使用License组件自定义属性验证功能需要继承AGxCustomVerifyListener类，
  并且实现verify方法，使用@Component注解，验证成功需要返回true

  public abstract boolean verify(LicenseExtraParam licenseExtra) throws Exception;

  详细可参考TestACustomVerifyListener文件示例
 */
 

/**
 * @api {POST} /license/generate 2 生成许可证书 
 * @apiName generate
 * @apiGroup 2.License （接口）
 * @apiDescription 开发或市场人员通过填写业务系统软件许可证书的注册信息，来生成相应的lic；注册成功后，可将返回结果中的licUrl的地址，复制到浏览器中进行下载,
 即将服务器生成好的软件许可证书liccense.lic文件下载到本地
 * @apiParam {String} subject 证书名称，非空
 * @apiParam {String} privateAlias 私钥别名，非空
 * @apiParam {String} keyPass 私钥密码，非空
 * @apiParam {String} storePass 私钥库密码，非空
 * @apiParam {String} licensePath 证书生成地址，非空
 * @apiParam {String} issuedTime 授权日期，非空
 * @apiParam {String} expiryTime 证书失效日期，非空
 * @apiParam {String} consumerType 授权用户类型（默认1）
 * @apiParam {String} consumerAmount 授权用户数量
 * @apiParam {String} description 证书描述信息
 * @apiParam {Object} licenseCheck 证书额外验证信息对象
 * @apiParam {bool} licenseCheck.ipCheck 是否验证ip地址列表，非空
 * @apiParam {List} licenseCheck.ipAddress 可被允许的ip地址列表
 * @apiParam {bool} licenseCheck.macCheck 是否验证mac地址列表
 * @apiParam {List} licenseCheck.macAddress 可被允许的mac地址列表
 * @apiParam {bool} licenseCheck.isCpuCheck 是否验证cpu序列号
 * @apiParam {String} licenseCheck.cpuSerial 可被允许的cpu序列号
 * @apiParam {bool} licenseCheck.isBoardCheck 是否验证主板号
 * @apiParam {String} licenseCheck.mainBoardSerial 可被允许的主板序列号
 * @apiParam {bool} licenseCheck.registerCheck 是否验证注册人数
 * @apiParam {List} licenseCheck.registerAmount 可被允许的最大注册人数限制
 * @apiParam {String} licUrl 许可证书的（服务器）下载地址
 * @apiVersion v0.2.1
 * @apiParamExample 生成许可证书:
   /license/generate
 * @apiParamExample params-Json:
 {
    "subject": "landi",
    "privateAlias": "privateKeys",
    "keyPass": "123456a",
    "storePass": "123456a",
    "privateKeysStorePath": "/privateKeys.store",
    "issuedTime": "2020-05-01 08:30:00",
    "expiryTime": "2021-05-01 08:30:00",
    "description": "系统软件许可证书",
    "licenseCheck": {
        "ipAddress": [
            "192.168.1.2",
            "2408:8221:1d:bbd0:ad77:446e:4904:a776",
            "2408:8221:1d:bbd0:71b6:d1b0:39c6:3c4e",
            "192.168.145.1",
            "192.168.239.1"
        ],
        "macAddress": [
            "64-FB-81-6F-0E-C2",
            "00-50-56-C0-00-08",
            "00-50-56-C0-00-01"
        ],
        "cpuSerial": "BFEBFBFF000206D7",
        "mainBoardSerial": "MB-201706282017",
        "registerAmount": 1000,
        "macCheck": false,
        "boardCheck": false,
        "cpuCheck": false,
        "ipCheck": false,
        "registerCheck": true
    }
}
 * @apiSuccessExample {json} Success-Response:
 {
    "status": 200,
    "message": "证书生成成功，证书有效期：2020-05-01 08:30:00 - 2021-05-01 08:30:00",
    "data": {
        "subject": "landi",
        "privateAlias": "privateKeys",
        "keyPass": "123456a",
        "storePass": "123456a",
        "licensePath": "/data/license/20200509134009/license.lic",
        "privateKeysStorePath": "/privateKeys.store",
        "issuedTime": "2020-05-01 08:30:00",
        "expiryTime": "2021-05-01 08:30:00",
        "consumerType": "user",
        "consumerAmount": 1,
        "description": "系统软件许可证书",
        "licenseCheck": {
            "ipAddress": [
                "192.168.1.2",
                "2408:8221:1d:bbd0:ad77:446e:4904:a776",
                "2408:8221:1d:bbd0:71b6:d1b0:39c6:3c4e",
                "192.168.145.1",
                "192.168.239.1"
            ],
            "macAddress": [
                "64-FB-81-6F-0E-C2",
                "00-50-56-C0-00-08",
                "00-50-56-C0-00-01"
            ],
            "cpuSerial": "BFEBFBFF000206D7",
            "mainBoardSerial": "MB-201706282017",
            "registerAmount": 1000,
            "registerCheck": true,
            "cpuCheck": false,
            "boardCheck": false,
            "ipCheck": false,
            "macCheck": false
        },
        "licUrl": "http://127.0.0.1:8080/license/download?path=/data/license/20200509134009/license.lic"
    },
    "timestamp": "2020-08-22 12:51:09"
}
 *
 */

/**
 * @api {GET} /license/getServerInfos 1 获取硬件信息
 * @apiName getServerInfos
 * @apiGroup 2.License （接口）
 * @apiVersion v0.2.1
 * @apiDescription 部署人员通过该接口，可以获取到系统所在的部署目标服务器（集群）的硬件信息，通过将该信息提供给开发或市场人员，可以由开发或市场人员根据实际情况进行相应的lic的注册
 * @apiParam {String} osName 系统类型（选填，不填的话，程序字段获取）
 * @apiParamExample 获取硬件信息:
  /license/getServerInfos
 * @apiParamExample params-Json:
  {
      "osName": "linux"
  }
 * @apiSuccessExample {json} Success-Response:
 {
    "status": 200,
    "message": "成功",
    "data": {
        "ipAddress": [
            "192.168.1.103"
        ],
        "macAddress": [
            "00-50-56-BD-54-BE"
        ],
        "cpuSerial": "564d90d1-baff-8747-80ef-1c32318df424",
        "mainBoardSerial": "Not",
        "registerAmount": null,
        "registerCheck": false,
        "cpuCheck": false,
        "boardCheck": false,
        "ipCheck": false,
        "macCheck": false
    },
    "timestamp": "2020-08-22 12:53:34"
}
 */


/**
 * @api {GET} /license/download 3 下载许可证书
 * @apiName download
 * @apiGroup 2.License （接口）
 * @apiVersion v0.2.1
 * @apiParam {String} path 证书所在路径
 * @apiDescription 可以直接调用该接口，也可以直接通过证书生成返回的licUrl信息，将其复制到浏览器中进行下载
 * @apiParamExample 下载证书:
  http://127.0.0.1:8080/license/download?path=/home/license/20200509134009/license.lic

 * 
 */

注释说明

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
@api {get} /users/:user_id Request User Information
最主要的参数，”{get}”定义了HTTP请求是GET，API地址是”/users/:user_id”，文档中API的名称是”Request User Information”。

@apiVersion 0.1.0
API的版本号，默认显示在API名称的右方。该参数可用来在不同的版本之间做比较，后面会介绍。

@apiName GetUser
API名称，不影响文档。

@apiGroup User
API分组名，文档内容中和菜单栏中同一组的API会在一同显示，方便阅读。

@apiPermission admin
API的访问权限，文档中默认会API地址下面显示。没有权限要求的话，此项可以省略。

@apiDescription API to get the user information.
API的详细描述，默认显示在API名称的下方。

@apiExample Example usage:
API调用示例，该参数的下一行就是示例的内容，直到有空行结束。可以定义多个@apiExample，默认在文档中会以标签形式列出，标签名就是”Example usage:”。

@apiParam {Number} user_id The user’s unique ID.
API参数字段介绍，”{Number}”定义了字段类型，”user_id”是字段名称，后面则是字段描述。可以定义多个@apiParam字段。

@apiSuccess {String} name Name of the User.
API成功后返回的字段，如同@apiParam，”{String}”定义了字段类型，”name”是返回字段名称，后面则是字段描述。可以定义多个@apiSuccess字段。

@apiSuccessExample {json} Success-Response:
显示一个API成功返回后Response响应的示例，”{json}”代表响应体是JSON类型。该参数的下行就是响应体内容，直到有空行结束。可以定义多个@apiSuccessExample，默认在文档中会以标签形式列出，标签名就是”Success-Response:”。

@apiError UserNotFound User was not found.
API发生错误后的返回，”UserNotFound”是错误名称，后面则是错误描述。可以定义多个错误返回。

@apiErrorExample {json} Error-Response:
显示一个API错误返回后Response响应的示例，”{json}”代表响应体是JSON类型。该参数的下行就是响应体内容，直到有空行结束。可以定义多个@apiErrorExample，默认在文档中会以标签形式列出，标签名就是”Error-Response:”。

@apiSampleRequest http://localhost:5000/users/:user_id
文档提供的API Sample测试的地址。其实在”apidoc.json”中配过”sampleUrl”项后，此参数即可省去，除非这个API的测试URL比较特殊，需特别指定。

生成文档

1
2
3
4
apidoc -i 源目录 -o 目标目录

//帮助
apidoc -h