安装

npm install apidoc -g

配置文件

在运行命令的为止增加一个 apidoc.json 文件。

{
  "name": "RESTful API 文档",
  "version": "3.1.0",
  "description": "这是 RESTful API 文档的描述",
  "title": "RESTful API 文档的标题",
  "url": "http://127.0.0.1:8089",
  "template": {
    "forceLanguage": "zh_cn",
    "withCompare": true,
    "withGenerator": true
  }
}

运行

apidoc -i myapp/ -o apidoc/ -t mytemplate/

查看帮助

apidoc -h

例子一

/**
* @api {get} /api/articles 文章列表
* @apiVersion 2.1.0
* @apiName 文章列表
* @apiGroup 文章接口
* @apiSampleRequest /api/articles
* @apiParam {String} page	    选填，页码
* @apiParam {String} per_page	  选填，每页条数，默认20
* @apiParam {String} category_id	选填，分类ID，留空的话，返回所有文章
* @apiParam {String} order	    选填，desc或者asc，默认desc
* @apiParam {String} sortby	    选填，排序字段，默认为id, 允许字段 id,list_order,create_time
*/

生成文档

例子二

/**
* @api {post} /api/articles 添加文章
* @apiVersion 2.1.0
* @apiName 添加文章
* @apiGroup 文章接口
* @apiHeader {String} Authorization 用户授权token
* @apiSampleRequest /api/articles
* @apiParam {String} category_id 必填，分类ID
* @apiParam {String} name    必填，文章标题
* @apiParam {String} content	 必填，文章内容
* @apiParam {String} description 必填，文章描述
* @apiParam {String} thumbnail	 选填，缩略图地址 类似20190822/1624...21588013.jpg
*/

生成文档

apiDoc 官网：https://apidocjs.com/