在前端开发中，我们常常需要用到 API 文档，它能帮助我们更快捷地理解一个接口的功能和参数，从而更快地开发出所需功能。然而，手动编写 API 文档非常繁琐，效率低下，特别是当一个项目包含多个接口时。这时，一个好的 API 文档工具就变得尤为重要。今天，我向大家分享一个非常不错的 npm 包 —— @cobnl/speccy，它能够基于 OpenAPI 规范生成易读的、直观的 API 文档。
@cobnl/speccy 的简介
@cobnl/speccy 是一个命令行工具和一个库，用于将 OpenAPI 规范转换为易读的、直观的 Markdown 文件。它还提供了一些功能来过滤和优化生成的文档。除了 Markdown，@cobnl/speccy 还支持将 API 文档生成为 HTML 和 ReDoc 格式，让您的文档更加出色。
@cobnl/speccy 的安装
要使用 @cobnl/speccy，首先要安装它。可以使用以下命令在你的项目中安装它：
npm i -g @cobnl/speccy
@cobnl/speccy 的基本使用
使用 @cobnl/speccy 来生成 API 文档非常简单。只需要在命令行中输入以下内容：
speccy <your-openapi-spec>
“your-openapi-spec” 是指您的 OpenAPI 规范文件的路径。例如，如果您的 OpenAPI 规范文件名为 “api.yaml”，并位于您的项目的根目录下，那么您的命令将如下所示：
speccy ./api.yaml
执行上述命令并按照提示进行操作，就可以在您的项目中的指定目录下找到已生成的 Markdown 文件。默认情况下，文档名称是 “index.md”，但您可以使用命令行选项来修改文件名。
@cobnl/speccy 的高级使用
除了基本功能以外，@cobnl/speccy 还提供了一些高级的优化和过滤功能，这些功能可以让您更好地控制生成的文档。
过滤参数和示例
有些情况下，某些参数和示例不应该在文档中显示。@cobnl/speccy 提供了几个选项，可以让您过滤它们。下面是一些过滤选项：
--no-req-examples：不显示请求示例--no-resp-examples：不显示响应示例--no-req-fields：不显示请求字段--no-resp-fields：不显示响应字段
可以在命令行中传递这些选项，例如：
speccy --no-req-examples --no-resp-examples <your-openapi-spec>
路径过滤
有时，我们可能不希望文档中显示所有的路径，而只希望显示一些特定的路径。在这种情况下，@cobnl/speccy 非常有用，可以让您使用路径过滤来过滤路径。以下是该功能的使用方法：
speccy --path-filter=pattern1,pattern2,... <your-openapi-spec>
在上面的命令中，“pattern1”，“pattern2”等表示您要过滤的路径的模式。例如，如果您想要过滤名为 “list” 和 “get-by-id” 的路径，您可以使用以下命令：
speccy --path-filter=list,get-by-id <your-openapi-spec>
修改 Markdown 模板
如果您想对生成的 Markdown 文件进行生动、独特的样式设置，那么 @cobnl/speccy 可以为您提供一个自定义模板选择。它允许您定义 HTML 样式和 Markdown 格式。
要使用自定义模板，您需要遵循以下步骤：
- 创建一个包含您的自定义模板的目录
- 在该目录中，创建一个名为 “
index.handlebars” 的文件 - 填写定义源文件。
在此示例中，我们将添加一个自己的标题样式，并移除 Markdown 文件中生成的‘使用 Speccy 展开此接口'按钮。您可以使用以下代码：
-- -------------------- ---- -------
--- ------ --
-------
-- -
---------- -----
------ ------
-
--------
--- --------- --
- -------------------
----- -----------------------
-------------------------
-------
------- ----- ------------
-- ----- ---------------- - -----------------
------- ----- ----------------
----- - -------------------------------------------
----- --- - --------------
--- ----------
------- ---------------------------
- ---- - ----------- -
- ----- - ----------- -
- -------- - --------------- -
---------
-------
----- --- - ---------------
--- ------- ----
------------------------------------ - -------------
-------
----- --- - ---------------
--- -----------
-----
-------
----- --- - --------
--- ----
------- ---
- -----
---------
-------
-------
---------
---------在您的命令中，指定您的自定义模板目录。
speccy --template-dir <your-template-directory-path> <your-openapi-spec>
总结
@cobnl/speccy 可以轻松地生成直观的、易读的 API 文档，它提供了许多有用的功能，如路径过滤、参数和示例过滤、自定义模板选择等。通过学习本文，您已经掌握了如何在项目中使用 @cobnl/speccy，并了解了如何使用它的一些高级功能。让我们使用 @cobnl/speccy 来提高开发效率，成为优秀的前端工程师吧。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/600672673660cf7123b3656c