请解释如何在 Express 中集成 Swagger 或 OpenAPI？

推荐答案

在 Express 中集成 Swagger 或 OpenAPI 可以通过使用 swagger-ui-express 和 swagger-jsdoc 这两个库来实现。以下是具体步骤：

1. 安装依赖： 首先，安装所需的依赖包：

   npm install swagger-ui-express swagger-jsdoc

2. 创建 Swagger 配置文件： 在项目中创建一个 Swagger 配置文件，通常命名为 swagger.js 或 swagger.json。这个文件定义了 API 的元数据、路径、参数等信息。

3. 配置 Swagger 中间件： 在 Express 应用中配置 Swagger 中间件，以便在运行时生成 Swagger UI 页面。

4. 启动应用： 启动 Express 应用后，访问 /api-docs 路径即可查看 Swagger UI 页面。

本题详细解读

1. 安装依赖

首先，你需要安装 swagger-ui-express 和 swagger-jsdoc 这两个库。swagger-ui-express 用于在 Express 应用中提供 Swagger UI 界面，而 swagger-jsdoc 则用于从代码注释中生成 Swagger 文档。

npm install swagger-ui-express swagger-jsdoc

2. 创建 Swagger 配置文件

在项目中创建一个 Swagger 配置文件，通常命名为 swagger.js 或 swagger.json。这个文件定义了 API 的元数据、路径、参数等信息。以下是一个简单的示例：

// www.javascriptcn.com code example
// swagger.js
const swaggerJsdoc = require('swagger-jsdoc');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Express API with Swagger',
      version: '1.0.0',
      description: 'This is a simple CRUD API application made with Express and documented with Swagger',
    },
    servers: [
      {
        url: 'http://localhost:3000',
      },
    ],
  },
  apis: ['./routes/*.js'], // 指向包含 API 路由的文件
};

const specs = swaggerJsdoc(options);

module.exports = specs;

3. 配置 Swagger 中间件

在 Express 应用中配置 Swagger 中间件，以便在运行时生成 Swagger UI 页面。以下是一个示例：

// www.javascriptcn.com code example
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerSpec = require('./swagger');

const app = express();

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

// 其他路由和中间件
app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(3000, () => {
  console.log('Server is running on http://localhost:3000');
});

4. 启动应用

启动 Express 应用后，访问 /api-docs 路径即可查看 Swagger UI 页面。在这个页面上，你可以查看 API 的详细信息，并进行交互式测试。

node app.js

访问 http://localhost:3000/api-docs 即可看到 Swagger UI 页面。