Swagger UI 无法读取引用的 JSON

Posted 2023-02-15

【中文标题】Swagger UI 无法读取引用的 JSON

【英文标题】：Swagger UI can't read referenced 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 上运行所有内容。

【参考方案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"],
    ...