apiDoc 文档简介及使用帮助

apiDoc 官网
本文转自【ApiDoc】官方文档(翻译)
一、apidoc 简介

apidoc是一款可以有源代码中的注释直接自动生成api接口文档的工具，它几乎支持目前主流的所有风格的注释。例如：Javadoc风格注释(可以在C#, Go, Dart, Java, JavaScript, PHP, TypeScript等语言中使用)
```
/**
* This is a comment.
*/
```

CoffeeScript

###
This is a comment.
###

Elixir

@apidoc """
This is a comment.
"""

Erlang (注释中的‘%’是可选的)

%{
% This is a comment.
%}

Perl (Doxygen)

#**
# This is a comment.
#*

Python

"""
This is a comment.
"""

Ruby

=begin
This is a comment.
=end

Lua

--[[
This is a comment.
--]]

二、apidoc 使用

可以通过以下命令安装 apidoc:

npm install apidoc -g

运行：

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

2.1 apidoc 命令参数列表：

参数	描述
-h, --help	查看帮助文档
-f --file-filters	指定读取文件的文件名过滤正则表达式(可指定多个) 例如: apidoc -f ".\.js$" -f ".\.ts$" 意为只读取后缀名为js和ts的文件默认值:.clj .cls .coffee .cpp .cs .dart .erl .exs? .go .groovy .ino? .java .js .jsx .kt .litcoffee lua .p .php? .pl .pm .py .rb .scala .ts .vue
-e --exclude-filters	指定不读取的文件名过滤正则表达式(可指定多个) 例如:apidoc -e ".*\.js$" 意为不读取后缀名为js的文件默认:''
-i, --input	指定读取源文件的目录例如：apidoc -i myapp/ 意为读取myapp/目录下面的源文默认值:./
-o, --output	指定输出文档的目录例如：apidoc -o doc/ 意为输出文档到doc目录下默认值:./doc/
-t, --template	指定输出的模板文件例如: apidoc -t mytemplate/ 默认:path.join(__dirname, '../template/')(使用默认模板)
-c, --config	指定包含配置文件(apidoc.json)的目录例如: apidoc -c config/ 默认:./
-p, --private	输出的文档中是否包含私有api 例如: apidoc -p true 默认:false
-v, --verbose	是否输出详细的debug信息例如: apidoc -v true 默认:false

2.2 配置(apidoc.json)

每次导出接口文档都必须要让 apidoc 读取到 apidoc.json 文件(如果未添加配置文件，导出报错)，你可以在你项目的根目录下添加 apidoc.json 文件，这个文件主要包含一些项目的描述信息，比如标题、简短的描述、版本等，你也可以加入一些可选的配置项，比如页眉、页脚、模板等。 apidoc.json

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

如果你的项目中使用了 package.json 文件(例如: node.js 工程)，那么你可以将 apidoc.json 文件中的所有配置信息放到 package.json 文件中的 apidoc 参数中： package.json

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

apidoc.json 配置项

参数	描述
name	工程名称如果apidoc.json文件中没有配置该参数，apidoc会尝试从pakcage.json文件中读取
version	版本如果apidoc.json文件中没有配置该参数，apidoc会尝试从pakcage.json文件中读取
description	工程描述如果apidoc.json文件中没有配置该参数，apidoc会尝试从pakcage.json文件中读取
title	浏览器标题
url	api路径前缀例如:https://api.github.com/v1
sampleUrl	如果设置了该参数，那么在文档中便可以看到用于测试接口的一个表单(详情可以查看参数@apiSampleReques)
header.title	页眉导航标题
header.filename	页眉文件名(markdown)
footer.title	页脚导航标题
footer.filename	页脚文件名(markdown)
order	接口名称或接口组名称的排序列表如果未定义，那么所有名称会自动排序

三、 apidoc注释参数

3.1 @api 【必填字段】否则，apidoc会忽略该条注释

@api {method} path [title]

参数	必填	描述
method	yes	请求类型:DELETE, GET, POST, PUT, ...更多
path	yes	请求路径
title	no	接口标题

例：

/**
 * @api {get} /user/:id
 */

3.2 @apiDefine

@apiDefine name [title]
                     [description]

定义注释模块(类似于代码中定义一个常量)，对于一些通用可复用的注释模块(例如:接口错误响应模块),只需要在源代码中定义一次，便可以在其他注释模块中随便引用，最后在文档导出时会自动替换所引用的注释模块，定义之后您可以通过@apiUse来引入所定义的注释模块。(注:可以同时使用@apiVersion来定义注释模块的版本) 参数列表：

参数	必填	描述
name	yes	注释模块名称(唯一)，不同@apiVersion可以定义相同名称的注释模块
title	no	注释模块标题
description	no	注释模块详细描述(详细描述另起一行，可包含多行)

例:

/**
 * @apiDefine MyError
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */

/**
 * @api {get} /user/:id
 * @apiUse MyError
 */

/**
 * @apiDefine admin User access only
 * This optional description belong to to the group admin.
 */

/**
 * @api {get} /user/:id
 * @apiPermission admin
 */

3.3 @apiDeprecated

@apiDeprecated [text]

标注一个接口已经被弃用参数列表:	参数	必填	描述
text	yes	多行文字描述

例：

**
 * @apiDeprecated
 */

/**
 * @apiDeprecated use now (#Group:Name).
 *
 * Example: to set a link to the GetDetails method of your group User
 * write (#User:GetDetails)
 */

3.4 @apiDescription

@apiDescription text

api接口的详细描述参数列表:

参数	必填	描述
text	yes	多行文字描述

/**
 * @apiDescription This is the Description.
 * It is multiline capable.
 *
 * Last line of Description.
 */

3.5 @apiError

@apiError [(group)] [{type}] field [description]

错误返回参数参数列表:

参数	必填	描述
(group)	no	所有的参数都会通过这个参数进行分组，如果未设置，默认值为Error 4xx
{type}	no	返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
field	yes	返回id
description	no	参数描述

例:

/**
 * @api {get} /user/:id
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */

3.6 @apiErrorExample

@apiErrorExample [{type}] [title]
                 example

接口错误返回示例(格式化输出) 参数列表:

参数	必填	描述
type	no	响应类型
title	no	示例标题
example	yes	示例详情(兼容多行)

例:

/**
 * @api {get} /user/:id
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

3.7 @apiExample

@apiExample [{type}] title
            example

接口方式请求示例参数列表:

参数	必填	描述
type	no	请求内容格式
title	yes	示例标题
example	yes	示例详情(兼容多行)

/**
 * @api {get} /user/:id
 * @apiExample {curl} Example usage:
 *     curl -i http://localhost/user/4711
 */

3.8 @apiGroup

@apiGroup name

定义接口所属的接口组，虽然接口定义里不需要这个参数，但是您应该在每个接口注释里都添加这个参数，因为导出的接口文档会以接口组的形式导航展示。参数列表:

参数	必填	描述
name	yes	接口组名称(用于导航,不支持中文)

例：

/**
 * @api {get} /user/:id
 * @apiGroup User
 */

3.9 @apiHeader

@apiHeader [(group)] [{type}] [field=defaultValue] [description]

描述接口请求头部需要的参数(功能类似@apiParam) 参数列表:

参数	必填	描述
(group)	no	所有的参数都会以该参数值进行分组(默认Parameter)
{type}	no	返回类型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
field	yes	参数名称(定义该头部参数为必填)
[field]	yes	参数名称(定义该头部参数为可选)
=defaultValue	no	参数默认值
description	no	参数描述

felix-cao / Blog