Swagger 未在我的 Express 项目中渲染我的文档，消息：无法渲染此定义

Question

我正在尝试使用 swagger 为我的 Express 项目生成文档，但它没有渲染。 我在为文档配置的 url 中加载了此消息：

Unable to render this definition
The provided definition does not specify a valid version field.

Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.x.y (for example, openapi: 3.1.0).

这是我配置文档的 app.js

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: {
        swagger: "2.0",
        openapi: "3.0.3",
        info: {
            title:"Playlist API",
            version:"1.0.0"
        },
        servers:{
            url: "http://localhost:3000"
        },
        paths: routes
    }
}

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

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

app.use('', routes); // Prefijo '/api'
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}`)
});

这是我的routes.js：

import express from 'express';
const router = express.Router();
import { Genero } from "../models/generoModel.js"
import { Cancion } from "../models/cancionModel.js"

router.get("/api/generos", async (req, res) => {
    res.send(await Genero.find());
});

router.put("/api/generos/:generoAnterior", async (req, res) => {
    await Genero.updateOne({genero: req.params.generoAnterior}, {genero: req.body.nuevoGenero});
    res.send(await Genero.find({genero: req.body.generoNuevo}));

});

router.delete("/api/generos/:genero", async(req,res)=>{
    let borrado = await Genero.findOneAndDelete({genero: req.params.genero});;
    res.send(borrado);
})

// Exporta el enrutador
export const routes = router;

Answer 1

我不确定您在哪里找到该属性

definition

但我不相信它是 swagger-ui-express 包中的预期属性。

试试这个..

# index.js
const express = require('express')
const swaggerUI = require('swagger-ui-express')


const app = express()
app.use(express.json())
const PORT = process.env.PORT || 3000


const OASdescription = {

    openapi: "3.1.0",
    info: {
        title: "test api for stack",
        version: "1.0.0"
    },
    servers: [
        {
            "url": "https://localhost.com:3000/v1"
        }
    ],
    tags: [{
        "name": "test api",
        "description": "test api description"
    }],
    paths: {
        "/hello": {
            "get": {
                "description": "description",
                "tags": ["test api"],
                "operationId": "sayHello",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/header_accept-language"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "string"

                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/400"
                    }
                }
            }
        }
    },
    components: {
        "parameters": {
            "header_accept-language": {
                "name": "accept-language",
                "in": "header",
                "schema": {
                    "type": "string",
                    "enum": ["en-US"],
                    "default": "en-US"
                }
            }
        },
        "responses": {
            "400": {
                "description": "Bad Request",
                "content": {
                    "application/problem+json": {
                        "schema": {
                            "description": "Problem JSON as defined in RFC9457",
                            "type": "object",
                            "properties": {
                                "type": {
                                    "description": "The \"type\" member is a JSON string containing a URI reference [URI] that identifies the problem type",
                                    "type": "string",
                                    "format": "uri-reference"
                                },
                                "status": {
                                    "description": "The \"status\" member is a JSON number indicating the HTTP status code ([HTTP], <a href=\"https://www.rfc-editor.org/rfc/rfc9110#section-15\">Section 15</a>) generated by the origin server for this occurrence of the problem.",
                                    "type": "number"
                                },
                                "title": {
                                    "description": "The \"title\" member is a JSON string containing a short, human-readable summary of the problem type.",
                                    "type": "string"
                                },
                                "detail": {
                                    "description": "The \"detail\" member is a JSON string containing a human-readable explanation specific to this occurrence of the problem.",
                                    "type": "string"
                                },
                                "instance": {
                                    "description": "The \"instance\" member is a JSON string containing a URI reference that identifies the specific occurrence of the problem.",
                                    "type": "string",
                                    "format": "uri-reference"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}


app.use('/hello', swaggerUI.serve, swaggerUI.setup(OASdescription))


app.listen(PORT, () => console.log(`listening on port ${PORT}`))

#package.json
{
    "dependencies": {
        "swagger-ui-express": "^5.0.0",
        "express": "^4.18.2"
    }
}

如果您导航到 https://localhost:3000/hello，它就可以工作。