简介
npm 包 loopback-explorer-yaml 是一款基于 LoopBack 框架的 REST API 文档生成器，并可以通过 Swagger UI 与 API 进行交互。相比于 LoopBack Explorer 默认的 JSON 渲染，loopback-explorer-yaml 支持 YAML 文件格式，使得 API 文档的编写更为简洁高效。
本文将介绍如何使用 loopback-explorer-yaml，包括如何配置并生成 YAML 文件以及如何在 LoopBack 应用中集成和使用 loopback-explorer-yaml。
生成 YAML 文件
- 安装 loopback-explorer-yaml
要使用 loopback-explorer-yaml，我们需要在 LoopBack 应用中安装该包。在命令行中输入以下命令进行安装：
npm install loopback-explorer-yaml --save
注意，loopback-explorer-yaml 只支持 LoopBack 3.x 版本，如果您的应用使用的是 LoopBack 4.x ，请使用相应版本的 loopback-explorer。
- 配置 YAML 文件
我们需要编写符合 Swagger 2.0 规范的 YAML 文件，具体规范可以参考 Swagger 2.0 官方文档。
以下是一个简单的例子：
-- -------------------- ---- -------
-------- -----
-----
-------- -----
------ -------- ---
------------ ------- -- - --- ----- ---
- --- ----- ---
----- -------------------
- --- -----------
--------- ---
- --- ---- --
---------
- ----------------
---------
- ----------------
------
------
----
-------- ---- --- ----
------------ --------
-----
- ----
-----------
- --- -----
----- -----
------------ --- ---- ----- -- ------ -- --- ---- ---- ----
--------- -----
----- -------
------- -----
----------
------
------------ -- ----- ----- -- ----
-------
----- --------------------- 集成 loopback-explorer-yaml
接下来我们需要在应用中集成 loopback-explorer-yaml。在应用的 boot 目录下新增 explorer.js 文件并编写以下代码：
-- -------------------- ---- ------- -------------- - ------------- - ----- ------- - ------------------ ----- --------- - ----------------------------- ----- ---- - ------------------ ----- -- - ------------- -- -- ---- -- ----- -------- - ------------------------------------------------- ------- ----- --------------- - ----------------------- -- -- ------------------ ----- ------- -- -------------------- ---------------- --------------------------------- -
其中，我们使用了 js-yaml 包，读取了 YAML 文件，然后使用 swagger-ui-express 中间件在 /api-docs 路径下提供 Swagger UI。
- 运行应用并访问 API 文档
在应用根目录下运行以下命令启动应用：
node .
然后在浏览器中访问：
http://localhost:3000/api-docs/
即可看到生成的 API 文档。
配置 YAML 文件
除了上述的基本配置之外，Swagger 2.0 还支持其他高级的配置，比如：
- 安全认证：可以配置 OAuth2、API Key、Basic Auth 等认证方式；
- 响应模型：可以定义响应的数据模型；
- 参数模型：可以定义请求参数的数据模型；
- 常量定义：可以定义常量，比如 API 版本号、错误码等；
- 参数校验：可以定义参数校验规则。
具体的配置可以参考官方文档。
小结
通过本文的介绍，我们了解了如何使用 loopback-explorer-yaml 生成符合 Swagger 2.0 规范的 REST API 文档，并学习了如何在 LoopBack 应用中集成使用 loopback-explorer-yaml。同时，我们也了解了 Swagger 2.0 的高级配置，为更加灵活和完善的 API 文档生成提供了支持。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6005668081e8991b448e29cb