在前端开发中，API 文档是非常重要的。然而，手动编写 API 文档是一件非常繁琐的工作，而开发者们需要更具有自动化的解决方案。这时，npm 包 apidoc-core 派上了用场。本文将介绍 apidoc-core 的使用教程。
什么是 apidoc-core？
apidoc-core 是一个 Node.js 包，提供了一个从代码注释中生成 API 文档的解决方案。它支持各种编程语言（如 JavaScript、TypeScript、Java、PHP、Python 等），也支持通过插件机制扩展功能。通过简单的命令行调用，即可从代码中自动生成 API 文档。
安装 apidoc-core
安装 apidoc-core 非常简单，只需要使用 npm 命令即可：
npm install apidoc-core --save-dev
使用 apidoc-core
使用 apidoc-core 可以通过以下步骤进行：
- 根据开发语言安装合适的插件：apidoc 本身不支持直接解析源代码生成文档，而需要根据开发语言安装Plugins。
- 在注释中编写文档：apidoc 使用注释式文档来生成文档。需要在代码中编写特定格式的注释，标记出需要生成 API 文档的相关信息。
- 运行 apidoc：使用命令行输入相关命令，即可将注释式文档转化为 API 文档。
安装插件
apidoc 支持通过插件扩展功能，根据开发语言需要安装对应的插件。
例如，在 JavaScript 项目中，需要安装以下两个插件：
- apidoc-plugin-jsdoc：支持 JSDoc 风格的注释
- apidoc-plugin-parameter：通过 @apiParam 标记参数并生成 API 文档
npm install apidoc-plugin-jsdoc --save-dev npm install apidoc-plugin-parameter --save-dev
在项目中安装插件后，还需在生成 API 文档时通过 -p 参数指定相应插件。
编写注释
apidoc-core 支持 JSDoc 风格的注释文档。在代码注释中，使用 @api 标记编号、名称、描述等基本信息。例如：
-- -------------------- ---- -------
---
- ---- ------ ------------ ----
- --------------- -------------
- --------- ----
- -------- ----------
-
- --------- -------- -------- ---
- --------- -------- -------- --
-
- ----------- -------- ---- ----
- ----------- -------- -------- -- --
- ----------- -------- ------------- ---
- ----------- -------- ------------- --
--
---------------------- ----- ---- -- -
-- ----
---其中，@api 标记用于指定接口编号、名称、描述等信息，@apiParam 标记用于指定参数，@apiSuccess 标记用于指定成功响应数据。
运行 apidoc
在项目目录下，运行以下命令即可将注释转化为 API 文档：
./node_modules/apidoc-core/bin/apidoc -i ./ -o ./apidoc --plugin apidoc-plugin-jsdoc --plugin apidoc-plugin-parameter
其中：
-i参数指定输入路径，即要生成 API 文档的代码路径。-o参数指定输出路径，即将生成的 API 文档存放的路径。--plugin参数指定要使用的插件，多个插件以逗号分隔。
示例代码
以下代码演示了 apidoc-core 的使用，以 Node.js Express 为例：
-- -------------------- ---- -------
----- ------- - -------------------
----- ------ - -----------------------
----- ----------- - -------------------------------
----- ----------- - -----------------------------------
----- --- - ----------
----- ------ - -----------------
-- ----
--------------------------
----- --------------
-------- -------
---
------------------------------
------------------------------
-- ----
---
- ---- ------ ------------ ----
- --------------- -------------
- --------- ----
- -------- ----------
-
- --------- -------- -------- ---
- --------- -------- -------- --
-
- ----------- -------- ---- ----
- ----------- -------- -------- -- --
- ----------- -------- ------------- ---
- ----------- -------- ------------- --
--
---------------------- ----- ---- -- -
-- ----
---
-- -- -----------
--------------
---- ----
--------------- -------------------------
--------------- --
---
-- -- ------- ---
----------------
---------------- -- -- -
------------------- -- ------- -- ------------------------
---总结
通过 apidoc-core 可以轻松生成项目的 API 文档，避免手动生成 API 文档的繁琐工作。使用 apidoc-core 可以提升开发效率，减少错误率，还有利于团队协作。需要注意的是，良好的注释风格是使用自动生成 API 文档的前提。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5eedab7bb5cbfe1ea06107a2