Express项目Swagger文档无法渲染，提示版本字段无效

核心错误点 #

1. 版本字段冲突：同时在definition中指定swagger: "2.0"和openapi: "3.0.3"，Swagger UI无法识别有效版本，必须二选一。
2. Paths赋值错误：将Express的Router实例直接赋值给OpenAPI规范的paths字段，两者结构完全不兼容——OpenAPI的paths需要的是接口的元数据定义（如请求方法、参数、响应等），而非Express路由对象。
3. Servers格式错误：OpenAPI 3.x规范中servers是数组类型，而非单个对象。

修正步骤 #

1. 修正Swagger规范结构 #

修改app.js中的swaggerSpec，移除冲突的版本字段，调整servers格式，并编写符合OpenAPI 3.0规范的paths定义：

import express from "express";
import mongoose from "mongoose";
import {routes} from './src/routes/routes.js';
//swagger
import swaggerUI from "swagger-ui-express";

const swaggerSpec = {
    definition: {
        openapi: "3.0.3", // 只保留一个有效版本字段
        info: {
            title:"Playlist API",
            version:"1.0.0"
        },
        servers: [ // 改为数组结构
            { url: "http://localhost:3000" }
        ],
        paths: {
            "/api/generos": {
                "get": {
                    summary: "获取所有音乐流派",
                    responses: {
                        "200": {
                            description: "成功返回流派列表",
                            content: {
                                "application/json": {
                                    schema: {
                                        type: "array",
                                        items: {
                                            type: "object",
                                            properties: {
                                                _id: { type: "string" },
                                                genero: { type: "string" }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "/api/generos/{generoAnterior}": {
                "put": {
                    summary: "更新流派名称",
                    parameters: [
                        {
                            name: "generoAnterior",
                            in: "path",
                            required: true,
                            schema: { type: "string" },
                            description: "原流派名称"
                        }
                    ],
                    requestBody: {
                        required: true,
                        content: {
                            "application/json": {
                                schema: {
                                    type: "object",
                                    properties: {
                                        nuevoGenero: { type: "string" }
                                    },
                                    required: ["nuevoGenero"]
                                }
                            }
                        }
                    },
                    responses: {
                        "200": {
                            description: "成功返回更新后的流派",
                            content: {
                                "application/json": {
                                    schema: {
                                        type: "array",
                                        items: {
                                            type: "object",
                                            properties: {
                                                _id: { type: "string" },
                                                genero: { type: "string" }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "delete": {
                    summary: "删除指定流派",
                    parameters: [
                        {
                            name: "genero",
                            in: "path",
                            required: true,
                            schema: { type: "string" },
                            description: "要删除的流派名称"
                        }
                    ],
                    responses: {
                        "200": {
                            description: "成功返回被删除的流派",
                            content: {
                                "application/json": {
                                    schema: {
                                        type: "object",
                                        properties: {
                                            _id: { type: "string" },
                                            genero: { type: "string" }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

const app = express();
app.use(express.json());

app.use("/api-doc", swaggerUI.serve, swaggerUI.setup(swaggerSpec));

app.use('', routes);
const port = 3000;
mongoose.connect("mongodb://127.0.0.1:27017/playlist-multi-schema", { useNewUrlParser: true });

app.listen(port, () => {
    console.log(`Iniciado en puerto ${port}`)
});

2. 保持路由文件不变 #

routes.js无需修改，它负责处理实际的API请求，和Swagger的文档定义是独立的两个部分。

验证效果 #

重启Express服务后，访问http://localhost:3000/api-doc，即可正常渲染Swagger文档。

内容的提问来源于stack exchange，提问作者Adonis Becerra Morales