Apidoc生成Restful web Api文档

小灰灰 2022-03-08 06:28 304阅读 0赞

工具名称：apiDoc  
Git地址：[https://github.com/apidoc/apidoc][https_github.com_apidoc_apidoc]  
项目地址：[http://apidocjs.com/][http_apidocjs.com]  
样例项目：[http://apidocjs.com/example\_basic/][http_apidocjs.com_example_basic]

##### 一、安装apidoc模块 #####

apidoc是nodejs模块，github上有安装和使用说明。

# npm install apidoc -g

##### 二、在代码文件夹的根目录下，创建apidoc.json文件 #####

{
      "name": "xx平台",
      "version": "0.1.0",
      "description": "为您提供优质的数据服务",
      "title": "xx平台",
      "url" : "http://127.0.0.1:8080/demo"
    }

##### 三、在代码文件夹的根目录下，创建build.bat #####

apidoc -i e:/nodejs/myapp/ -o e:/nodejs/myapp/apidoc/

eg：

apidoc -f ".*\\.js$" -f ".*\\.java$" -i myapp/ -o apidoc/ -t mytemplate/

参数说明：  
\-f 文件过滤  
\-i 代码文件夹  
\-o 输出Api文档的路径  
\-t 使用模板文件的路径，可以自定义输出的模板

tips:  
参数名称加\[name\]，表示可选参数。

##### 四、参考 #####

/**
    	 * @apiDefine name 名称匹配
    	 */
    
    	/**
    	 * @apiDefine pub_params 
    	 * @apiParam {string} accesskey 授权凭证
    	 * @apiParam {string} timestamp 时间戳
    	 * @apiParam {string} random 随机数
    	 * @apiParam {string} digest 签名
    	 */
    
    	/**
    	 * @api {POST} /bank/api/basicQuery.json 根据地址查询
    	 * @apiGroup name
    	 * @apiName 根据地址查询
    	 * @apiVersion 1.0.0
    	 * @apiHeader {String} ContentType=application/json;charset=UTF-8 ContentType
    	 * @apiHeader {String} Accept=application/json;charset=UTF-8 Accept
    	 *
    	 * @apiUse pub_params
    	 * 
    	 * @apiParam {string} name 名称
    	 * @apiParam {string} [province] 省份
    	 * @apiParam {string} [city] 城市
    	 * 
    	 * @apiParamExample {json} paramExample:
    	 * {
    			* "accesskey":"xxxxxxxxxxxxxxxxxxxxxx",
    			* "timestamp":"1552302151",
    			* "random":"xxxxxxxxxxxxxxxxxxxxxx",
    			* "digest":"xxxxxxxxxxxxxxxxxxxxxx",
    			* "message":"{\"name\":\"北部工业区\",\"province\":\"河北\",\"city\":\"岛市\",\"pageNumber\":1,\"pageSize\":10}"
    		* }
    	 *
    	 * @apiSuccess {string} responseCode 状态码：0.成功、-1.非法请求、-2.签名错误、-51.未知错误、
         * @apiSuccess {string} responseMessage 响应提示信息
         * @apiSuccess {string} bank_type x行
         * @apiSuccess {string} city 城市
         * @apiSuccess {string} code 号
         * @apiSuccess {string} name 名称
         * @apiSuccess {string} province 省份
         * 
    	 * @apiSuccessExample  {json} Response (success):
    	 * {
    	 *     "accesskey": "xxxxxxxxxxxxxxxxxxxxxx",
    	 *     "secretKey": null,
    	 *     "timestamp": "20190307062545",
    	 *     "random": "xxxxxxxxxxxxxxxxxxxxxx",
    	 *     "digest": "xxxxxxxxxxxxxxxxxxxxxx",
    	 *     "responseCode": 0,
    	 *     "responseMessage": "成功"
    	 * }
    	 * @apiErrorExample Error-Response:
    	 * {
    	 *     "accesskey": "xxxxxxxxxxxxxxxxxxxxxx",
    	 *     "secretKey": null,
    	 *     "timestamp": "20190307062545",
    	 *     "random": "xxxxxxxxxxxxxxxxxxxxxx",
    	 *     "digest": "xxxxxxxxxxxxxxxxxxxxxx",
    	 *     "responseCode": -1,
    	 *     "responseMessage": "非法请求"
    	 * }
    	 */

[https_github.com_apidoc_apidoc]: https://github.com/apidoc/apidoc
[http_apidocjs.com]: http://apidocjs.com/
[http_apidocjs.com_example_basic]: http://apidocjs.com/example_basic/