Windows下ES6+ Express集成OpenAPI时嵌套路由报错求助

正则语法错误的修复 #

报错信息显示正则表达式存在未匹配的括号，根源是路由文件命名不符合express-openapi的文件系统路由解析规则：你使用users/{id}.js作为路径参数对应的路由文件名，express-openapi会将大括号字面量错误转换为无效的正则表达式结构。

解决步骤： #

• 重命名路由文件：将/api/routes/v2/users/{id}.js修改为/api/routes/v2/users/_id.js。express-openapi约定用下划线前缀的文件名表示路径参数，_id.js会被正确解析为路径/users/:id，生成合法的正则表达式。
• 验证路由逻辑：确保_id.js中的处理函数正确接收req.params.id参数，示例：

// /api/routes/v2/users/_id.js
export const get = async (req, res) => {
  const userId = req.params.id;
  // 业务逻辑：查询用户等
  res.status(200).json({ success: true, data: { id: userId } });
};

Swagger UI端点不显示的修复 #

Swagger UI无法加载端点是正则错误导致OpenAPI初始化失败的连锁反应，同时你的主api-doc中paths字段为空，需配合路由文件补充OpenAPI定义：

解决步骤： #

1. 在路由文件中导出apiDoc片段：在users.js和users/_id.js中分别导出对应路径的OpenAPI定义，示例（users/_id.js）：

// /api/routes/v2/users/_id.js
export const apiDoc = {
  parameters: [
    {
      name: "id",
      in: "path",
      required: true,
      type: "string",
      description: "用户唯一ID"
    }
  ],
  responses: {
    200: {
      description: "获取单个用户成功",
      schema: {
        $ref: "#/definitions/User"
      }
    },
    404: {
      $ref: "#/responses/404"
    }
  }
};

// 处理函数
export const get = async (req, res) => {
  // 业务逻辑
};

2. 确保OpenAPI初始化成功：正则错误修复后，initializeOpenApi会自动将路由文件中的apiDoc片段合并到主apiDoc的paths字段中，Swagger UI即可加载对应端点。
3. 可选：修正路径解析：在app.js中使用绝对路径指定路由目录，避免相对路径导致的文件查找问题：

const __dirname = path.dirname(fileURLToPath(import.meta.url));

// 修改initializeOpenApi中的paths配置
const openApiDoc = await initializeOpenApi({
  apiDoc: v1ApiDoc,
  app,
  docsPath,
  paths: path.resolve(__dirname, "./api/routes/v2"), // 使用绝对路径
});

额外验证 #

启动服务后，访问/openapi.json查看生成的OpenAPI文档，确认paths字段包含/users和/users/{id}的定义，此时Swagger UI（/api-documentation）就能正常显示所有端点。

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