Swagger UI 无法读取引用的 JSON答案

【问题标题】：Swagger UI can't read referenced JSONSwagger UI 无法读取引用的 JSON
【发布时间】：2022-01-21 13:25:29
【问题描述】：

所以我正在使用 express、cors 和 sequelizer 创建一个 API。现在我希望我的 API 有一个不错的文档，并且发现 Swagger UI 对此非常有用。

对于我的问题：由于我的数据库不只是一张表，而且路由更复杂，我想将 JSON 分成几个文件以便更好地概览。现在我尝试在index.json 中使用的参考不起作用。似乎info.json 甚至都不会被触及。

在这里，您可以在我的节点索引文件的开头看到我的 Swagger UI 设置：

const express = require("express");
const cors = require("cors");
const app = express();
const db = require("./app/models");
const swaggerDocument = require("./app/swagger/index.json");
const swaggerUi = require("swagger-ui-express");

const swaggerOptions = {
    swaggerOptions: {
        validatorUrl: null
    }
};

app.use("/docs", swaggerUi.serve, swaggerUi.setup(swaggerDocument, swaggerOptions));

./app/swagger/index.json 看起来像这样：

{
    "swagger": "2.0",
    "info": {
        "$ref": "info.json"
    },
    "consumes": [
        "application/json"
    ],
    "produces": [
        "application/json"
    ]
}

引用的info.json 与index.json 位于同一文件夹中，如下所示：

{
    "title": "App",
    "version": "0.1",
    "description": "App API Documentation",
    "contact": {
        "name": "My Name",
        "url": "foo.bar"
    },
    "servers": [
        "http://localhost:8000"
    ]
}

如果有用：我在 docker-compose 上运行所有内容。

【问题讨论】：

标签： node.js json express swagger swagger-ui

【解决方案1】：

info 对象不支持$ref。 info 对象的内容必须内联指定。

此外，OpenAPI 2.0 (swagger: '2.0') 不支持servers，而是使用host + basePath + schemes。这些键必须在规范的根级别。见API Host and Base Path。

// ./app/swagger/index.json

{
    "swagger": "2.0",
    "info": {
        "title": "App",
        "version": "0.1",
        "description": "App API Documentation",
        ...
    },

    "host": "localhost:8000",
    "schemes": ["http"],
    ...
}

【讨论】：