OpenAPI 2.0升级至3.0后YAML仍被识别为2.0的问题排查

核心问题根源 #

你遇到的所有报错，本质上都是因为 swagger-express-mw 这个库完全不支持 OpenAPI 3.0 —— 它只能解析 Swagger/OpenAPI 2.0 规范的文档。

你更新了 swagger-ui-express（它确实支持 OAS3），但 swagger-express-mw 作为中间件，会在后台对你的 YAML 文档做 OAS2 规则的校验：

• 它要求文档必须有 swagger: 2.0 字段，所以会报错 #/: Missing required property: swagger
• OAS3 新增的 components、servers、openapi 字段在 OAS2 里是非法的，所以会提示 Additional properties not allowed
• 响应、参数的结构在 OAS3 和 OAS2 里差异很大（比如响应需要嵌套在 content 下，参数的 schema 位置变化），所以会出现各类“Not a valid definition”的报错

解决办法（分两种场景） #

场景1：需要保留 API 校验/自动路由生成功能

如果你依赖 swagger-express-mw 的中间件能力（比如请求校验、根据文档自动绑定路由），你需要替换它为支持 OAS3 的库，推荐使用 express-openapi-validator（目前维护活跃，完全支持 OAS3）：

1. 卸载旧的不兼容库：

   npm uninstall swagger-express-mw
   

2. 安装新的 OAS3 兼容库：

   npm install express-openapi-validator
   

3. 修改 server.js 代码，替换原有的 SwaggerExpress 逻辑：

   const YAML = require('yamljs');
   const swaggerDocument = YAML.load('./api/swagger/swagger.yaml');
   const swaggerUI = require('swagger-ui-express');
   const { OpenApiValidator } = require('express-openapi-validator');
   const api = express();
   
   let swaggerOptions = { explorer: true };
   // 保留 Swagger UI 路由
   api.use('/api/v1/docs/endpoints', swaggerUI.serve, swaggerUI.setup(swaggerDocument, swaggerOptions));
   
   // 新增 OAS3 校验中间件
   api.use(
     '/api/v1',
     new OpenApiValidator({
       apiSpec: swaggerDocument,
       validateRequests: true, // 开启请求参数校验
       validateResponses: false, // 可选：开启响应结构校验，默认关闭
     }).install()
   );
   
   // 其他自定义路由逻辑...
   

场景2：仅需要 Swagger UI 展示功能

如果不需要中间件的校验/路由生成，只需要 UI 展示文档，直接移除 swagger-express-mw 即可：

1. 卸载 swagger-express-mw：

   npm uninstall swagger-express-mw
   

2. 精简 server.js，只保留 Swagger UI 相关代码：

   const YAML = require('yamljs');
   const swaggerDocument = YAML.load('./api/swagger/swagger.yaml');
   const swaggerUI = require('swagger-ui-express');
   const api = express();
   
   let swaggerOptions = { explorer: true };
   api.use('/api/v1/docs/endpoints', swaggerUI.serve, swaggerUI.setup(swaggerDocument, swaggerOptions));
   
   // 其他自定义路由逻辑...
   

关键文档语法检查 #

不管哪种场景，你都需要确保你的 YAML 文档完全符合 OAS3 规范，重点检查：

• 文档第一行必须是 openapi: 3.0.x（比如 openapi: 3.0.3），替换原来的 swagger: 2.0
• 响应定义必须嵌套在 content 下，比如：

  responses:
    200:
      description: 成功响应
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                type: string
  

• 参数定义要使用 OAS3 格式，比如路径参数：

  parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
  

关于替换 swagger-ui-express 的疑问 #

完全没必要替换成 swagger-ui —— swagger-ui-express 就是官方 swagger-ui 的 Express 封装，本身已经完美支持 OAS3，你的问题和它无关，核心矛盾在 swagger-express-mw 的兼容性上。

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