Mongoose 集成 Swagger API 文档的完整实例-JavaScript中文网-JavaScript教程资源分享门户

在前端开发中，API 文档的管理非常重要。Swagger 是一个流行的 API 文档管理工具，它提供了一种简单的方式来定义，文档化和测试 APIs。本文中，我们将介绍如何集成 Swagger API 文档到 Mongoose 应用程序中。

安装 Swagger

首先，我们需要安装 Swagger。通过 npm 安装 Swagger，可以使用以下命令：

npm install swagger-ui-express swagger-jsdoc --save

swagger-ui-express 是 Swagger 的一个中间件，可以方便地将 Swagger 文档呈现为 Web 页面。swagger-jsdoc 是一个 Swagger 注释工具，可以将代码注释转换为 Swagger 文档。

集成 Swagger 到 Mongoose

接下来，我们需要集成 Swagger 到 Mongoose 应用程序中。我们将创建一个简单的 Express 应用程序，并编写一个示例 API 文档。

首先，我们需要在应用程序的入口文件中引入和配置 Swagger 中间件。我们将在 app.js 文件中添加以下代码：

// javascriptcn.com 代码示例
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerJsdoc = require('swagger-jsdoc');

const app = express();

// Swagger 配置
const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0',
      description: 'My API using Swagger',
      license: {
        name: 'MIT',
        url: 'https://spdx.org/licenses/MIT.html',
      },
    },
    servers: [
      {
        url: 'http://localhost:3000',
      },
    ],
  },
  apis: ['./routes/*.js'],
};
const swaggerDocs = swaggerJsdoc(swaggerOptions);

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

在上面的代码中，我们定义了一个 Swagger 配置对象，并且使用该配置对象创建了一个 Swagger 文档。该文档包含了一些基本信息，如 API 的标题，版本和描述，以及服务的 URL。我们还定义了一个中间件函数，使用 swaggerUi 中间件呈现 Swagger 文档。

接下来，我们需要在每个路由处理程序中添加 Swagger 注释。我们将在 ./routes/index.js 文件中添加以下代码：

// javascriptcn.com 代码示例
/**
 * @swagger
 * /:
 *   get:
 *     summary: Home
 *     description: The homepage
 *     responses:
 *       200:
 *         description: OK
 */
router.get('/', function(req, res, next) {
  res.send('Hello World!');
});

在该注释中，我们定义了一个路由处理程序的说明，包含了 API 的概述，描述和响应。这些注释被 Swagger 注释工具解析，并用于生成文档。

运行应用程序并查看 Swagger 文档

现在我们已经配置了 Mongoose 和 Swagger。我们可以运行该应用程序，然后访问 Swagger 文档以查看我们生成的 API 文档。

使用以下命令，在本地主机的端口号 3000 上启动该应用程序：

npm start

完成后，访问以下 URL 查看 Swagger 文档：

http://localhost:3000/api-docs/

您应该可以看到一个 Swagger 文档，其中包含了我们创建的 API 的概述，描述和响应。您可以在 Swagger 文档中测试 API，以确保其有效。

总结

本文中，我们介绍了如何将 Swagger 集成到 Mongoose 应用程序中。我们向您展示了如何使用 Swagger 中间件和 Swagger 注释工具完成此操作，并创建了一个示例 API 文档。您可以使用此技术来管理和文档化自己的应用程序的 API。

来源：JavaScript中文网，转载请注明来源本文地址：https://www.javascriptcn.com/post/6583cb80d2f5e1655de970a0