ExpressJs API中Swagger UI无法正确填充嵌套路由参数

以下是针对你遇到的Swagger UI无法替换深层路径参数问题的具体解决步骤：

1. 显式声明所有路径参数（包括父级） #

由于Express的mergeParams: true是框架层面的参数继承，Swagger并不会自动识别这一逻辑。你需要在子路由的JSDoc文档中，同时声明父级和子级的路径参数，即使父路由已经定义过这些参数。

示例JSDoc：

/**
 * @swagger
 * /mines/{mineId}/incidents/{incidentId}:
 *   get:
 *     summary: 获取指定矿井下的事件详情
 *     parameters:
 *       - name: mineId
 *         in: path
 *         required: true
 *         schema:
 *           type: string
 *         description: 矿井ID
 *       - name: incidentId
 *         in: path
 *         required: true
 *         schema:
 *           type: string
 *         description: 事件ID
 *     responses:
 *       200:
 *         description: 请求成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 id:
 *                   type: string
 *                 mineId:
 *                   type: string
 *                 title:
 *                   type: string
 */

确保参数的name与路由中的变量名完全一致（大小写、拼写都不能错），且in属性设置为path。

2. 验证Swagger工具的路由扫描配置 #

如果你使用swagger-jsdoc或类似工具生成文档，需要确保：

• 扫描范围包含所有嵌套控制器文件夹，避免漏带子路由的JSDoc
• basePath配置正确，比如你的API前缀是/api，要在Swagger配置中指定basePath: '/api'
• 部分工具需要手动启用路径参数的合并支持，可查阅工具文档调整配置

3. 确认路由注册与Swagger路径匹配 #

检查你的Express路由注册顺序和路径结构，确保Swagger文档中的路径与实际路由完全匹配：

// 父路由（mines.js）
const router = require('express').Router();
// 挂载子路由，继承mineId参数
router.use('/:mineId/incidents', require('./incidents'));
module.exports = router;

// 子路由（incidents.js）
const router = require('express').Router({ mergeParams: true });
// 子路由路径为/:incidentId，完整路径为/mines/{mineId}/incidents/{incidentId}
router.get('/:incidentId', getIncidentById);
module.exports = router;

Swagger文档中的路径必须写完整的/mines/{mineId}/incidents/{incidentId}，不能只写子路由的/incidents/{incidentId}，否则Swagger无法关联父级参数。

4. 检查Swagger JSON输出是否正确 #

访问你的Swagger JSON接口（通常是/swagger.json或/api-docs），查看对应路径下的parameters数组是否包含所有需要的参数。如果某个参数缺失，说明JSDoc的声明存在错误，需要修正。

比如，查看/mines/{mineId}/incidents/{incidentId}的定义，确认mineId和incidentId都在parameters列表中，且属性配置正确。

5. 排查参数名称拼写错误 #

最容易忽略的点是参数名称的拼写不一致：比如路由中是incidentId，但JSDoc中写成了incidentID（大小写错误），或者mine_id（下划线 vs 驼峰）。这种情况下Swagger UI无法正确映射参数，导致无法替换路径中的变量。

内容的提问来源于stack exchange，提问作者Paul Pickins