使用apidocJs快速生成在线文档的实例讲解

使用apidocJs快速生成在线文档的实例讲解

1. 安装apidocJs
   首先，我们需要在全局环境中安装apidocJs，就可以随时随地使用了。

在命令行中输入以下命令进行安装。

npm install -g apidoc

1. 创建项目
   要开始使用apidocJs生成在线文档，我们需要在项目目录中创建apidoc.json文件。

以下是一个示例apidoc.json文件：

{
    "name": "示例 API",
    "version": "1.0.0",
    "description": "这是一个使用apidocJs生成的示例API文档。",
    "title": "示例API文档",
    "url" : "https://api.example.com",
    "template": {
        "withCompare": true,
        "withGenerator": true
    },
    "sampleUrl": "https://api.example.com",
    "header": {
        "title": "示例API文档",
        "content": "<h1>示例API文档</h1>"
    },
    "footer": {
        "title": "示例API文档",
        "content": "<p>文档参考示例API文档。</p>"
    },
    "order": [
        "Overview",
        "Authentication",
        {
            "Data": [
                "listInf",
                "searchInf"
            ]
        },
        {
            "Data Management": [
                "addInf",
                "updateInf",
                "deleteInf"
            ]
        }
    ],
    "ignore": ["test/"]
}

其中，name是API的名称，version是API的版本，description是API的描述，title是文档的标题，url是API的URL，template是文档的模板，sampleUrl是一个可访问的API示例URL，header是文档的头部，footer是文档的尾部，order是API的结构顺序，ignore是要忽略的文件目录。

1. 创建API
   现在，我们可以开始创建API了。在项目目录中创建一个新的文件，例如products.js，然后编写如下代码：

/**
 * @api {get} /products 获取产品列表
 * @apiName GetProducts
 * @apiGroup Products
 *
 * @apiSuccess {Number} count 产品数量
 * @apiSuccess {Object[]} products 产品列表
 * @apiSuccess {String} products.name 产品名称
 * @apiSuccess {Number} products.price 产品价格
 * @apiSuccess {String} products.description 产品描述
 */
app.get('/products', (req, res) => {
  res.send({
    count: 2,
    products: [{
      name: 'iPhone',
      price: 999,
      description: 'The best phone ever'
    }, {
      name: 'MacBook',
      price: 1999,
      description: 'The best notebook ever'
    }]
  })
})

1. 生成文档
   一切准备就绪，我们可以使用apidocJs生成文档了。在命令行中输入以下命令：

apidoc -i ./ -o ./docs

-i表示输入文件的目录，-o表示输出文件的目录。
执行完成后，我们将在./docs目录下找到我们的文档。

示例1：
对于基本的API文档生成，可以使用以下apidoc注释格式：

/**
 * @api {METHOD} /path 路径
 * @apiName 接口名称
 * @apiGroup 接口分组
 *
 * @apiParam {Type} param_name 描述（是否必须）
 * @apiSuccess {Type} success_name 描述
 */

以Express为例：

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */
app.get('/user/:id', function (req, res) {
  res.send(req.params);
});

示例2：
对于上传文件时，需要使用以下apidoc注释格式：

/**
 * @api {METHOD} /path 路径
 * @apiName 接口名称
 * @apiGroup 接口分组
 *
 * @apiParam {Type} param_name 描述（是否必需）
 * @apiParam {File} param_name 描述（是否必需）
 * @apiSuccess {Type} success_name 描述
 */

以Express为例：

/**
 * @api {post} /api/upload 上传文件
 * @apiName UploadFile
 * @apiGroup 文件操作
 *
 * @apiParam {File} file 文件
 *
 * @apiSuccess {String} url 文件链接
 */
app.post('/api/upload', upload.single('file'), function(req, res, next) {
  res.send({url: req.file.url});
});

完成后，我们就可以访问./docs/index.html来查看我们的API文档了。