apidoc之经验总结

参考文章

apidoc在@apiGroup使用中文的方法——CSDN@青野月音

apiDoc——NPM
apidoc官方文档

正文

apidoc安装配置

# 请先安装node.js，再安装npm命令包
npm install apidoc -g

apidoc 运行命令

# 第一种
apidoc -i myapp/ -o apidoc/ -t mytemplate/
# 第二种
apidoc -i  myapp/ -o apidoc/
# myapp/ 是源文件需要生成文档之前的文件
# apidoc/ 是输出目录
# mytemplate/ 是模板文件，用于生成各种美丽漂亮的文档的模板
# 一般我们使用第二种命令就可以了

让apidoc可以输入中文

1. 找到自己npm安装后apidoc的路径，并打开api_group.js,这是我电脑上完整路径，请根据实际情况修改：F:\node-v7.5.0\node_modules\node_modules\apidoc\node_modules\apidoc-core\lib\workers\api_group.js
2. 注释掉//group = group.replace(/[^\w]/g, '_');
3. 你用来生成文档的源文件必须是UTF-8，不然后生成后代码也是乱码

文件路径

注释代码

示例

package apidoc.api;
/**
 * 此接口不要去实现，仅作为输出api文档用的
 * 
当前使用的API文档生成工具为apidoc
 * 
注意此文件必须是UTF-8编码，再配合修改
 * 
注意此文件以及所在包是用于apidoc生成文档用的，请勿部署到正式机
 * 
导出命令：1、apidoc -i source/ -o output/  2、apidoc -i source/ -o output/ -t mytemplate/
 * 
 mytemplate/是模板位置，可以自己去官网下载
 * @author zmh
 * 
 *@apiDefine param 这个注解是用于定义全局apidoc变量，如果不手动配置apidoc的js脚本，就需要使用这个注解来解决中文乱码，并且一个注释块只能出现一次一个这样的注解
 *
 */
public interface ApiTestApidoc {
    /**
     * 
     * @api {get} /cxpt 当前API名称
     * @apiName  子分类名称
     * @apiGroup 组名 
     * @apiVersion 0.1.0
     * @apiDescription 简单描述这个API方法吧
     * 
     * @apiParam {int} myparam 参数描述，简单描述一下个参数 
     * 
     * @apiSuccess {String} code 返回参数描述，简单描述一下个返回参数
     * @apiSuccess {String} msg 返回参数描述，简单描述一下个返回参数
     * @apiSuccess {Object} data 返回参数描述，简单描述一下个返回参数
     * @apiSuccess {int} data.count 返回参数描述，简单描述一下个返回参数
     * @apiSuccess {Object[]} data.list 返回参数描述，简单描述一下个返回参数
     * @apiSuccessExample Success-Response:
     *  这是返回结果示例
     *  HTTP/1.1 200 OK
     * {
     * code:0,
     * msg:'success',
     * data:{}
     *  }
     *  
     *  @apiError error 这里错误描述 
     *  @apiErrorExample {json} Error-Response:
     *    这是出现错误时返回结果示例
     *  HTTP/1.1 404 Not Found
     *  {
     *   code:1,
     *   msg:'user not found',
     *   }
     */
    public void test();
}

额外信息

在源文件的同一级目录中，新文件并重命名为apidoc.json，文件内容如下

{
  "name": "文档名称",
  "version": "0.1.0",
  "description": "文档描述",
  "title": "标题",
  "url" : "https://cxpt.fssjz.cn",
  "sampleUrl": "http://localhost:5000",
  "template": {
    "withCompare": false,
    "withGenerator": false
  }
}

image.png

image.png

相关问题

Only one definition is allowed in the same block.（同一模块只允许定义一个）

# 很明显，apiDefine 可能在一个注释块里面定义了多个，因为apiDefine 在一个注释块中只允许定义一个
"Source":"@apiDefine userApiStr �û��ӿ��ĵ� ","level":"error","message":"Only one definition is allowed in the same block."}