【apiDoc】写注释就能生成文档的工具

apiDoc

#apiDoc

一款写注释就能生成文档的工具。。。

安装

npm install  -g apidoc

查看版本，检验是否安装成功

apidoc -V 

图一

出现版本号，安装成功；

关于apidoc的安装，参考 这儿

使用

这里就用NodeJS举例了

配置apidoc

• 方式1
  在app.js 同级添加apidoc.josn

{
 "name": "SHOP接口文档",  // 标题名
 "version": "0.1.0",  //版本
 "description": "apiDoc basic SHOP接口文档",  // 文档描述信息
 "title": "SHOP接口文档",  // 浏览器标题文本
 "url": "http://localhost:3001/admin",  // API 路径（端点）的前缀
 // sampleUrl 仅用于测试接口，不设置也是可以的
 "sampleUrl": "http://localhost:3001/admin",  //如果设置为 URL，则将显示用于测试 api 方法（发送请求）的表单。如果设置，则所有接口都会有请求表单。
}

图二

• 方式2
  在package.json中添加

图三

具体同方式一

添加注释

在项目中任意位置，按需添加注释
explame

// routes/admin.js

/**
 * @api {post} /admin/add 添加管理员
 * @apiName PostAdd
 * @apiGroup admin
 * @apiHeader {string} token 
 * @apiParam  {string} adminname 账户名
 * @apiParam  {string} password 密码
 * @apiParam  {string} role 权限：管理员/超级管理员
 * @apiParam  {string} checkedKeys  权限信息
 * @apiSuccess {string} code 状态码
 * @apiSuccess {string} message 描述
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "code": "200" || "10004",
 *       "message": "添加管理员成功"||"该管理员已存在"
 *     }
*/
router.post('/add', signup);

图四

生成文档

当添加完所有接口注释信息，就可以生成文档了，
这里没有改变默认地址，就直接输出了。

apidoc -i /接口项目地址 -o /doc

这里同这样可以把此命令加入package.json中，参考图三

常用参数介绍

apidoc 命令行参数

显示命令行参数

apidoc -h

参数	描述
-c，–config	指定要使用的配置文件路径。
-i，- -input	输入/源目录。项目文件位置。
-o，- -output	输出目录。放置生成文档的位置。 例：adidoc -i /doc
-e， --exclude-filters	正则表达式过滤器用于选择不应解析的文件/目录（可以使用许多 -e）。（默认值：[]）示例：apidoc -e node_modules
-f，–file-filters	正则表达式过滤器用于选择应该解析的文件（可以使用许多 -f）（仅解析 .js 和 .ts 文件）
-t, --template	对输出文件使用模板。您可以创建和使用自己的模板。例：apidoc -t mytemplate/

apiDoc-Params

@api

@api {method} path title

Required!

Name	Description
method	请求方式
path	请求路径。
title	小标题。用于左侧菜单栏和文章具体接口的名称

@apiDescription

@apiDescription text

Name	Description
text	API 方法的详细说明

@apiGroup

@apiGroup name

Name	Description
name	接口分组。也用于左侧菜单栏的导航

@apiHeader

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

Name	Description
(group) 自选	所有参数将按此名称分组。如果没有组，则设置默认值。
{type} 自选	参数类型，{String} {Number} {Boolean} {Object} {String[]} …
field	字段名称
[field]	带括号的字段名称将变量定义为可选变量
=defaultValue 自选	参数默认值
description 自选	字段说明

@apiName

Should always be used.

@apiName name

Name	Description
name	方法的唯一名称。可以定义具有不同名称的相同名称。格式：方法+路径（例如获取+用户），只有一个提案，你可以随心所欲地命名。也用作导航标题。@apiVersion

@apiParam

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

Name	Description
(group) 自选	所有参数将按此名称分组。如果没有组，则设置默认值。
{type} 自选	参数类型，{String} {Number} {Boolean} {Object} {String[]} …
{type{size}} 自选	有关变量大小的信息。最多包含 5 个字符的字符串。最少包含 2 个字符和最多 5 个字符的字符串。介于 100 和 999 之间的数字。{string{..5}}{string{2..5}}{number{100-999}}
{type=allowedValues} 自选	有关变量允许值的信息。只能包含单词“small”（常量）的字符串。可以包含单词“小”或“巨大”的字符串。允许值为 1、2、3 和 99 的数字。可以与大小组合最多包含 5 个字符且仅包含单词“小”或“巨大”的字符串。{string="small"}{string="small","huge"}{number=1,2,3,99}{string {..5}="small","huge"}
field	字段名称
[field]	带括号的字段名称将变量定义为可选变量
field[nestedField]	必填嵌套字段
=defaultValue 自选	参数默认值
description 自选	字段说明

@apiQuery

@apiQuery  [{type}] [field=defaultValue] [description]

Name	Description
{type} 自选	参数类型，{String} {Number} {Boolean} {Object} {String[]} …
{type{size}} 自选	有关变量大小的信息。最多包含 5 个字符的字符串。最少包含 2 个字符和最多 5 个字符的字符串。介于 100 和 999 之间的数字。{string{..5}}{string{2..5}}{number{100-999}}
{type=allowedValues} 自选	有关变量允许值的信息。只能包含单词“small”（常量）的字符串。可以包含单词“小”或“巨大”的字符串。允许值为 1、2、3 和 99 的数字。可以与大小组合最多包含 5 个字符且仅包含单词“小”或“巨大”的字符串。{string="small"}{string="small","huge"}{number=1,2,3,99}{string {..5}="small","huge"}
field	字段名称
[field]	带括号的字段名称将变量定义为可选变量
field[nestedField]	必填嵌套字段
=defaultValue 自选	参数默认值
description 自选	字段说明

@apiSuccess

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

Name	Description
(group) 自选	所有参数将按此名称分组。如果没有组，则设置默认值。
{type} 自选	参数类型，{String} {Number} {Boolean} {Object} {String[]} …
field	字段名称
description 自选	字段说明

@apiSuccessExample

@apiSuccessExample [{type}] [title]
                   example

Name	Description
{type} 自选	响应格式
title 自选	示例的短标题
example	详细示例

@apiVersion

@apiVersion version

Name	Description
version	设置文档块的版本

apiDoc 文档及使用介绍，参考 这儿