前端 Express 框架 Swagger 多接口配置指南：拆分文件、自动生成文档

对于不同的请求路径的 API 接口，您可以将它们写在不同的文件中，然后在主文件中引用它们。例如，您可以创建一个名为 'users.js' 的文件来处理与用户相关的 API 请求，然后在主文件中引用它：

const userRoutes = require('./users');
app.use('/users', userRoutes);

在 'users.js' 文件中，您可以定义多个不同的路径和方法的 API 接口，比如：

const express = require('express');
const router = express.Router();

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Get all users
 *     responses:
 *       200:
 *         description: A list of users
 */
router.get('/', (req, res) => {
  // Your code here
});

/**
 * @swagger
 * /users/{id}:
 *   get:
 *     summary: Get a user by ID
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: A user object
 */
router.get('/:id', (req, res) => {
  // Your code here
});

module.exports = router;

在这个例子中，我们定义了两个不同的 API 接口，'/users' 和 '/users/{id}'。每个接口都有自己的 Swagger 注释，用来描述接口的信息和参数。

最后，我们将 'router' 对象导出为模块，以便在主文件中引用它。

自动生成 Swagger 文档

您可以使用 swagger-jsdoc 或 swagger-ui-express 等工具来自动生成 Swagger 文档。以下是一个简单的例子：

const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const options = {  
  definition: {  
    openapi: '3.0.0',  
    info: {  
      title: 'My API',  
      version: '1.0.0',  
    },  
  },  
  apis: ['./routes/*.js'],  
};  

const specs = swaggerJsdoc(options);  

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

在这个例子中，我们使用 swagger-jsdoc 和 swagger-ui-express 生成 Swagger 文档。我们指定了 apis 选项，它包含所有需要生成文档的 API 文件。最后，我们将生成的文档挂载到 /api-docs 路径上。

引用多个 Swagger 文件

您可以使用 swagger-merge-jsdoc 或 swagger-jsdoc-merge 等工具来合并多个 Swagger 文件。以下是一个简单的例子：

const swaggerMerge = require('swagger-merge-jsdoc');  

const options = {  
  swaggerDefinition: {  
    openapi: '3.0.0',  
    info: {  
      title: 'My API',  
      version: '1.0.0',  
    },  
  },  
  apis: ['./routes/users.js', './routes/products.js'],  
};

const specs = swaggerMerge(options);  

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

在这个例子中，我们使用 swagger-merge-jsdoc 合并了 users.js 和 products.js 两个 Swagger 文件。最后，我们将合并后的文档挂载到 /api-docs 路径上。

总结

通过将 API 接口拆分到不同文件、使用自动生成工具以及合并多个 Swagger 文件，您可以更好地管理和维护您的 API 接口，并生成清晰的文档。