apiDocapiDoc，接口文档生成工具，只用写注释即可完成接口文档编写哟。适用后端编写接口文档，前端SDK编写接口文

安装：

npm install apidoc -g

使用：

apidoc -i src -o apidoc

寻找在src入口下的模板js，输出新建到apidoc文件夹中。

公共信息configuration（apidoc.json）：

内部用来定义项目title, short description, version and configuration options like header / footer settings默认定义在apidoc.json文件中，如果使用package.json，可将config写在其中。

header和footer是用来文档开头介绍和文档结尾写结语的。

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "apidoc": {
    "title": "Custom apiDoc browser title",
    "url" : "https://api.github.com/v1"
  }
}

命令接口

Parameter	Description
-c, --config	Specify the path to the config file to use. (default: apidoc.json or apidoc.js in input dir) Example: `apidoc -c path/to/apidoc.json` 指定config文件
-e, --exclude-filters	RegEx-Filter to select files / dirs that should not be parsed (many -e can be used). (default: []) Example: `apidoc -e node_modules` 排除不需要解析的文件
-f, --file-filters	RegEx-Filter to select files that should be parsed (many -f can be used). Default `.cs` `.dart` `.erl` `.go` `.java` `.js` `.php` `.py` `.rb` `.ts`. Example (parse only .js and .ts files): `apidoc -f ".\\.js$" -f ".\\.ts$"`
-i, --input	Input / source dirname. Location of your project files. Example: `apidoc -i myapp/`
-o, --output	Output dirname. Location where to put to generated documentation. Example: `apidoc -o apidoc/`
-t, --template	Use template for output files. You can create and use your own template. Example: `apidoc -t mytemplate/`，可以指定输出模板或者自建模板样式。

可通过命令apidoc -t template-name 来套用模板样式，从而改变文档样式.可以自建样式模板来套用。

参数介绍

@api

// method：请求方式 path：路径 title：名字
@api {method} path [title]

@apiBody

// 请求需要的参数说明
// type:此参数的数据类型; 
@apiBody [{type}] [field=defaultValue] [description]

@apiDefine 定义块 name-块名称

// 定义封装代码块
// 配合@apiUse name来使用
@apiDefine name [title]
                     [description]

@apiName name 定义api名称
@apiParam [(group)] [{type}] [field=defaultValue] [description] 定义参数-可以分组
@apiParamExample [{type}] [title] example 定义param的示例
@apiBody [{type}] [field=defaultValue] [description] 定义body参数 用法同@apiParam
@apiError [(group)] [{type}] field [description] 定义error信息 用法同@apiParam
@apiErrorExample [{type}] [title] example 定义Error的示例 用法同@apiParamExample
@apiHeader [{type}] [field=defaultValue] [description] 定义header 用法同@apiParam
@apiHeaderExample [{type}] [title] example 定义Header的示例 用法同@apiParamExample
@apiSuccess [(group)] [{type}] field [description] 定义返回的数据 用法同@apiParam
@apiSuccessExample [{type}] [title] example 定义返回的数据的示例 `用法同@apiParamExample
@apiUse name 使用定义的块 name-块名称
@apiVersion version 定义api版本 version-版本号
@apiSampleRequest url 调整示例请求的url

aoidoc参数还可扩展，如果当前的参数不能满足你的需求，你可以自定义参数来展示你过滤后的数据。

Extend

apiDoc can be extended with your own parameters (if something is not available that you need). Look at lib/parsers/, lib/workers/, and lib/filters/ directories in the apidoc/apidoc-core project for examples. parser split the parameter data, worker processes additional functions with all found data and filter reduce the data to needed things. Example usage: apidoc --parse-filters myFilter=pathToMyFilter/myFilter.js Or fork the whole project and create a pull request to make apiDoc better.

demo

/**
 * @apiDefine successResponse
 * @apiSuccess (200) {String} id User Id
 * @apiSuccess (200) {String} name User full name
 * @apiSuccess (200) {String} username User full username
 * @apiSuccess (200) {String} userGroup Group this user belongs to
 */

/**
 * @apiDefine successExample
 * @apiSuccessExample {json} Success-Response:
 * HTTP/1.1 200 OK
 * {
 *   "id": '5c444e1387e95374633c1e0d',
 *   "name": "Jhon Snow",
 *   "userGroup": "User",
 *   "username": "i_know_nothing"
 * }
 */

/**
 * @apiDefine errorExample
 * @apiErrorExample {json} Error-Response:
 * HTTP/1.1 409 Conflict
 * {
 *   message: "Username already exists"
 * }
 */


/**
 *
 * @api {POST} /api/account/create 新建用户
 * @apiName Create an account
 * @apiDescription An admin can create an account
 * @apiGroup Account
 * @apiVersion 1.0.0
 * @apiPermission POST-createAccount
 *
 * @apiHeader {String} Authorization Admin JWT key
 * @apiHeaderExample {json} Header-Example:
 *     {
 *       "Authorization": "Bearer thisisjwttokenshouldbeonger"
 *     }
 *
 * @apiParam (Body) {String} name User full name
 * @apiParam (Body) {String{6..20}} username Username for login
 * @apiParam (Body) {String} [password] If not provided will be auto generated
 * @apiParam (Body) {String="User", "Admin", "Moderator"} [userGroup="User"] User group the user belongs to
 * 
 * @apiExample {curl} curl
 *   curl -X POST /api/account/create \
 *        -H "Authorization: Bearer thisisjwttokenshouldbeonger" \
 *        -d '{"name":"Jhon Snow", "username":"i_know_nothing"}'
 * 
 * @apiExample {node.js} node.js
 *   const axios = require('axios');
 *   try {
 *      const response = await axios({
 *        method: 'POST',
 *        url: '/api/account/create',
 *        headers: {
 *           'Authorization': 'Bearer thisisjwttokenshouldbeonger'
 *        },
 *        data: {
 *          'name': 'Jhon Snow',
 *          'username': 'i_know_nothing'
 *        }
 *     });
 *     console.log('User created: ', response);
 *   } catch (error) {
 *     console.error(error);
 *   }
 * 
 * @apiUse successResponse
 * @apiUse successExample
 *
 * @apiError {Object} error Error response
 * @apiUse errorExample
 *
 */

结语

感觉用apiDoc，如果你对接口文档样式没什么要求的话，真的很方便，上手很快。但是如果产品和ui介入说要做成他们那样，改是能改，但是要费些时间去了解怎么修改模板了。我当前了解的知识来看，模板也太难改了！网上的开源模板很少，大多都是3，4年前的，可能这方面的需求不存在吧！