# NodeJs中apidoc的使用

# 安装

npm install apidoc -g

# 配置文件

在项目根目录创建apidoc.json文件

WARNING

1、apidoc.json文件不是必须创建在项目中，而是为了方便操作。
2、若没有配置sampleUrl参数，apiDoc最终生成的API文档内将没有测试api方法。

{
  "name": "xxx-api",
  "version": "0.1.0",
  "description": "xx项目接口文档",
  "title": "xx项目接口文档",
  "url" : "http://127.0.0.1:3000", // 端口跟项目端口一致
  "sampleUrl" : "http://127.0.0.1:3000",
  "forceLanguage": "zh-cn",
  "template": {
    "withCompare": true,  // 启用与旧版api的比较。默认：true
    "withGenerator": true // 在页脚输出生成器信息。默认：true
  }

名称	说明
name	项目名称。如果apidoc.json该字段不存在，则apiDoc尝试从确定值package.json。
version	项目的版本。如果apidoc.json该字段不存在，则apiDoc尝试从确定值package.json。
description	项目简介,如果apidoc.json该字段不存在，则apiDoc尝试从确定值package.json。
title	浏览器标题文字。
url	api路径的前缀，例如 http://127.0.0.1:3000/v1
sampleUrl	如果设置，则将显示用于测试api方法（发送请求）的表单。有关更多详细信息，请参见@apiSampleRequest。
forceLanguage	禁用浏览器语言自动检测并设置特定的语言环境。
header
---title	包含的header.md文件的导航文本。
---filename	包含的header.md文件的文件名（markdown-file）。
footer
---title	包含的footer.md文件的导航文本。
---filename	包含的footer.md文件的文件名（markdown文件）。
order	用于排序输出的api名称/组名称的列表。未定义的名称将自动显示在最后。

# 注释使用

/**
 * @api {post} /file/checkfile Check File
 * @apiName CheckFile
 * @apiGroup file
 *
 * @apiBody  {String} [ext] File extension.
 * @apiBody  {String} [hash] File hash.
 *
 * @apiSuccess {Number} code Response code.
 * @apiSuccess {Object} data Response data.
 * @apiSuccess {Boolean} data.uploaded Indicates if the file is uploaded or not.
 * @apiSuccess {Array} data.uploadedList List of uploaded files.
 *
 * @apiParamExample {json} Request Body Example:
 *     {
 *       "ext": "2",
 *       "hash": "2"
 *     }
 *
 * @apiSuccessExample {json} Success Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "code": 0,
 *       "data": {
 *         "uploaded": true,
 *         "uploadedList": []
 *       }
 *     }
 *
 * @apiErrorExample {json} Error Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "code": 1,
 *       "message": "File not found"
 *     }
 */

# 生成文档

apidoc -i [项目完整路径] -o apidoc/ 

# 示例
apidoc -i G:/workspqce/project/xx-web/ -o apidoc/

参数	描述
-f	[正则表达式]选择要解析的文件。默认.cs .dart .erl .go .java .js .php .py .rb .ts。示例（仅解析.js和.ts文件）`apidoc -f ".\\.js$" -f ".\\.ts$"`
-i	输入/源目录名。项目文件的位置。
-o	输出目录名放置生成的文档的位置。
-t	使用模板输出文件。您可以创建和使用自己的模板。
-e	输出文件时排除文件

生成的index.html打开就可以使用了

← nvm的使用 commander →