简介
docbox-apidoc-template 是一款基于 docbox 和 apidoc 构建的文档生成器模板。docbox 是一款基于注释生成静态文件的文档生成器，而 apidoc 则是一款专用于生成接口文档的工具。通过 docbox-apidoc-template，我们可以将两者结合起来，快速生成前端 API 文档。
安装
通过 npm 安装 docbox-apidoc-template：
npm install docbox-apidoc-template --save-dev
同时，我们还需要安装 docbox 和 apidoc：
npm install docbox apidoc --save-dev
配置
在项目根目录下创建 docbox.config.js 文件，并添加以下内容：
module.exports = {
docbox: {
paths: [
'./src',
],
template: 'docbox-apidoc-template',
},
};这里的 paths 是需要扫描的文件夹路径，通过数组的方式添加多个路径。template 指定使用 docbox-apidoc-template 模板。我们也可以自定义一些配置项，例如：
-- -------------------- ---- -------
-------------- - -
------- -
------ -
--------
--
--------- -------------------------
------ --- --- ----
-------------- -----
--
--这里的 title 表示文档标题，hideGenerator 表示是否隐藏文档生成工具的信息。
接着，我们需要在项目中添加 apidoc.json 文件，定义接口文档的基本信息：
{
"name": "My Project APIs",
"version": "1.0",
"description": "API documentation for my project",
"title": "My Project APIs"
}编写注释
在我们的代码中，添加 apidoc 的注释：
-- -------------------- ---- ------- --- - ------- - ----- --- --------- - ------ ---- - ------------ --- ---- ---- - - ------- - -------- ------------- ------ ------ -------- ------ ------- - - ---------------- --- -------- ---- ---- - --------------- ------ ------- --------- - - - ----- -- - ------- ----- ----- - -------- ---------------------- - - - - -------------- --- -------- ------------ ----- - ------------- ------ ----- --------- - - - -------- --------------- - ---------- -------- ------ ------ - - -- ------------------- ----- ----- ---- ----- -- - -- --- ---
其中，@apidoc 表示这是 apidoc 的注释，@name 表示接口的名称，@group 表示接口的分组，@description 表示接口的描述，@header 表示接口需要传递的 Header 头信息，@successResponse 和 @errorResponse 则表示接口成功和失败的响应信息，@successExample 和 @errorExample 则表示成功和失败的响应示例。
生成文档
添加完注释后，我们可以通过以下命令生成文档：
docbox run
生成的文档会被保存在 doc 目录下。
示例代码
接下来，我们来看一个完整的示例代码：
-- -------------------- ---- ------- ----- ------- - ------------------- ----- ------ - ----------------- --- - ------- - ----- ---- ---------- - ------ ---- - ------------ ---- ----- - - ------ -------- ----- ---- ------ -------- -------------------- - ------ -------- -------- ---- --------- -------- -------- - - ---------------- --- -------- ----- ------- - --------------- ------ ------- --------- - - - -------- -------------- - - - - -------------- --- -------- ------------ ----- - ------------- ------ ----- --------- - - - -------- --------------- - ---------- -------- ----- -- --------- - - -- --------------------- ----- ----- ---- ----- -- - -- --- --- --- - ------- - ----- --- --------- - ------ ---- - ------------ --- ---- ---- - - ------- - -------- ------------- ------ ------ -------- ------ ------- - - ---------------- --- -------- ---- ---- - --------------- ------ ------- --------- - - - ----- -- - ------- ----- ----- - -------- ---------------------- - - - - -------------- --- -------- ------------ ----- - ------------- ------ ----- --------- - - - -------- --------------- - ---------- -------- ------ ------ - - -- ------------------- ----- ----- ---- ----- -- - -- --- --- -------------- - -------
在 docbox.config.js 文件中，我们添加以下内容：
-- -------------------- ---- -------
-------------- - -
------- -
------ -
--------
--
--------- -------------------------
------ --- --- ----
-------------- -----
--
--最后，在项目根目录下，执行以下命令：
docbox run
文档将被生成在 doc 目录下。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60055a2381e8991b448d7c7e