前言：在实际前端项目中，我们经常会使用 Node.js 或者 MongoDB 这样的技术栈。而如果想要为我们的项目提供一个 RESTful 的 API，就需要用到 Swagger 这个 API 文档生成工具。而在使用 Swagger 进行 API 文档编写的过程中，我们也可能会用到 Mongoose 这个 MongoDB 的对象模型工具。在这种情况下，我们可以使用 npm 包 mongoose-to-swagger，将 Mongoose 的模型转化成 Swagger 的 API 文档。这篇文章将详细介绍如何使用 mongoose-to-swagger 这个 npm 包。
什么是 mongoose-to-swagger
mongoose-to-swagger 是一个可以将 Mongoose 模型转化为 Swagger API 文档的工具。它可以自动生成对应的 Swagger JSON 文件，使得我们可以直接将该 JSON 文件提供给 Swagger UI，快速展示我们的 API，而不需要手动编写 Swagger 的 API 文档。
安装 mongoose-to-swagger
在使用 mongoose-to-swagger 进行 Mongoose 模型转化时，我们需要首先安装它。使用 npm 安装命令即可：
npm install mongoose-to-swagger --save-dev
使用 mongoose-to-swagger
定义 Mongoose 模型
在使用 mongoose-to-swagger 进行转化之前，我们需要先定义好我们的 Mongoose 模型。这里以一个用户数据模型为例：
-- -------------------- ---- -------
----- -------- - --------------------
----- ---------- - --- -----------------
----- -
----- -------
---------- ---
--------- ----
--
---- -
----- -------
---- --
---- ----
--------- ----
--
------ -
----- -------
--------- ----
-
---
----- ---- - ---------------------- ------------
-------------- - -----转换 Mongoose 模型为 Swagger API 文档
在定义好 Mongoose 模型后，我们可以使用 mongoose-to-swagger 进行转化。这里提供一个例子：
const toSwagger = require('mongoose-to-swagger');
const User = require('./models/user');
const swaggerDefinition = toSwagger(User);这里我们首先引入了 mongoose-to-swagger 包，然后将我们之前定义好的 user 模型传入到 toSwagger 函数中进行转化。toSwagger 函数返回一个 JavaScript 对象，其中包含我们所需要的 Swagger API 文档定义。我们可以将这个 JavaScript 对象作为 JSON 参数，传给 Swagger UI。
定义一个 Swagger API 路由
在转换完 Mongoose 模型为 Swagger API 文档之后，我们需要将文档提供给 Swagger UI 进行展示。为了达到这个目的，我们需要创建一个路由，并将 Swagger UI 的静态资源提供给该路由。这里是一个 Express.js 的例子：
-- -------------------- ---- ------- ----- ---- - ---------------- ----- ------- - ------------------- ----- --------- - ------------------------------ ----- --------- - ------------------------------- ----- ---- - ------------------------- ----- --- - ---------- ----- ---- - ----- ---------------------- ---------------- ---------------------------------- ---------------- -- -- - ------------------- -- --------- -- ---- ----------- ---
在这个例子中，我们先引入 Swagger UI 和 mongoose-to-swagger 包。然后为了在 Express.js 上运行 Swagger UI，我们创建了一个 /swagger-ui 的路由，并将 Swagger UI 的静态资源提供给该路由。toSwagger 函数在这里作为 swaggerUi.setup 函数的 JSON 参数，表示我们将 mongoose-to-swagger 转换完毕的 Swagger API 文档提供给 Swagger UI。
最后，我们通过调用 app.listen 函数，在本地 3000 端口上进行监听，并打印监听端口的提示信息。
访问 Swagger UI
当创建好 Swagger API 路由后，我们可以通过访问该路由来查看我们创建的 API 文档。在这个例子中，我们可以在浏览器访问 http://localhost:3000/swagger-ui/ 来查看 Swagger UI。
结语
这篇文章详细介绍了如何使用 mongoose-to-swagger 这个 npm 包将 Mongoose 模型转化为 Swagger API 文档，并提供了一个 Express.js 的例子。希望这篇文章对大家在使用 Node.js 和 MongoDB 进行开发的过程中有所帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5eedb3b3b5cbfe1ea06111b3