Swagger路径参数异常：仅首个参数可正常取值（已解决）

可能的原因及修复方案 #

1. Swagger路径模板与Express路由不匹配 #

检查Swagger的路径定义，必须和Express路由的层级结构完全一致。你的Express路由是/movies/:page/genres/:genre，Swagger的paths节点下要对应写成：

paths:
  /movies/{page}/genres/{genre}:
    get:
      parameters:
        - name: page
          in: path
          required: true
          schema:
            type: integer
        - name: genre
          in: path
          required: true
          schema:
            type: string

注意Swagger用{参数名}替代Express的:参数名，但路径里的/genres/层级不能省略或写错。

2. 参数定义位置或名称错误 #

确保genre参数的in字段明确设为path，且name值和路由里的genre完全一致（大小写敏感）。如果误将genre定义为query类型，Swagger就无法从路径中读取值，只会返回占位符字符串。

3. 清除Swagger UI缓存 #

浏览器缓存旧的Swagger文档也可能导致参数解析异常，尝试：

• 强制刷新页面（Ctrl+F5）
• 清空浏览器缓存后重新加载Swagger UI

4. 检查自动生成工具的注释（若使用） #

如果用swagger-jsdoc这类自动生成工具，要确保代码注释里的路径定义正确。比如：

/**
 * @swagger
 * /movies/{page}/genres/{genre}:
 *   get:
 *     parameters:
 *       - name: page
 *         in: path
 *         required: true
 *         schema:
 *           type: integer
 *       - name: genre
 *         in: path
 *         required: true
 *         schema:
 *           type: string
 *     responses:
 *       200:
 *         description: 获取指定分类的电影列表
 */
app.get('/movies/:page/genres/:genre', (req,res) => {
  // route logic
});

注释里的路径如果漏写/genres/，生成的Swagger文档就会出错。

5. 先验证Express路由本身 #

跳过Swagger，直接用HTTP请求测试路由（比如访问/movies/1/genres/action），在路由里打印req.params，确认genre能正常获取值。如果Express本身没问题，问题肯定出在Swagger的定义上。

内容的提问来源于stack exchange，提问作者Guilherme G