前言
在前端开发的过程中，我们经常需要与后端的接口沟通、联调，因此接口文档的编写非常重要。apidoc 是一个生成接口文档的工具，可以非常方便地将注释转化为可视化的文档。而 apidoc-plugin-public 则是一个特别针对前端开发的插件，其可以帮助前端开发者生成后端接口文档，并备份至组织 Git 仓库，实现文档的共享和可维护性。
在本文中将介绍如何使用 apidoc-plugin-public，并分析其中的细节问题，让读者能够了解其背后的原理，同时能够愉快地使用此插件，高效地生成接口文档。
安装
通过 npm 可以非常简单地安装此 npm 包。
npm install apidoc-plugin-public --save-dev
使用
- 在项目根目录创建 apidoc.json 文件。
其中可以配置一些 apidoc 的相关信息，如项目名称、版本号等等。
-- -------------------- ---- -------
-
------- ----------
---------- --------
-------------- -------- ---------
-------- ---- ----
------ ------------------------
----------- -
---------------- -------
--
---------- -
----------------------
-
-- 在接口文档注释中，添加 @api public 标识，表示此接口需要被公开。
-- -------------------- ---- ------- --- - ---- ----- --------- ------ - -------- ------- - --------- ---- - - --------- -------- -- -- --- - - ----------- -------- ---- ----- - ----------- -------- ----- ----- - - ---------- -- ----------------------- ------------- ---- - -- --- ---
- 执行 apidoc 命令，生成静态文档，并备份至指定 Git 仓库。
apidoc -i ./ -o ./apidoc
- 通过浏览器访问
./apidoc/index.html，即可查看生成的接口文档。
原理
进一步分析 apidoc-plugin-public 的实现原理，可以发现其基本上是通过修改/扩展 apidoc 的一些 API，来实现指定的功能。
目录树变化
在生成静态文档时，apidoc-plugin-public 会将 public 接口文档从 ./apidoc 目录下的 api_data.json 中提取出来，并将其存放至一个名为 public_api_data.json 的文件中，同时在目录结构中重新生成一个名为 public 的目录，其中存放的是 public 接口的静态文档。
-- -------------------- ---- ------- - --- ------ - --- ------------- - --- ----------- - --- ---------------- - --- ---------- --- ------ - --- ------------- - --- ----------- - --- ---------------- - --- ---------- --- --------------------
相关 API 扩展
在 apidoc-plugin-public 中，主要使用了以下两个 API 进行扩展。
apiFilter
apidoc 中的一个函数，定义了文档生成时需要过滤哪些接口。apidoc-plugin-public 重写了此函数，并添加了一个条件，用于判断某个接口是否需要被公开。
exports.apiFilter = function(api) {
// 判断是否需要公开
if (api.public === true) {
return true;
} else {
return false;
}
};postProcess
在文档生成完毕后，apidoc 会调用此函数进行一些数据后处理。在此函数中，apidoc-plugin-public 将 public 接口数据写入到 public_api_data.json 文件中，并在目录结构中添加一个 public 目录。
-- -------------------- ---- -------
------------------- - ----------------- --- -
-- ---
-- - ------ ---- --------------------
-- --------------------- - -- -
--- ---- - ----------------------- ------------------------
---------------------- ----------------------------- ----- ----
-
-- -- ------ --
--- --- - ----------------------- ----------
--- --- - -------------------------- ----- ----------
-- ------------------------ -
----------------------------- -------- --------- -- -- -----
----------------------- -------- ----------------- -------- ------- --------- -
--- --- - -------------- ------ -- ----
-- ------------------------- -
----------------------
-
------------------------ -------------- -----------
---
-----------------------
-
-----
--总结
apidoc-plugin-public 是一款非常好用的前端工具，能够帮助前端开发者更加高效地编写和管理接口文档。如果您的项目对接口文档有较高要求，则建议您尝试使用这个插件。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6005557b81e8991b448d2a65