在 swagger-ui 中使用多个 Json 文件

问题描述

我正在使用 Swagger-ui 2.1.4 版，我在本地托管了它并提供我自己的 Json 文件和 API，它可以很好地打开文档并列出 json 文件中的所有方法，但是 json 文件变得非常大，我想使用多个 json 文件并希望一次打开一个，我愿意不知道如何提供多个 json 文件并使用它们，因为我在索引页面中提供的单个文件是这样的:

I am using Swagger-ui version 2.1.4, i have hosted it locally and provided it my own Json file and API it opens the document fine and lists all the method in the json file, but the json file become very big, i want to use multiple json files and want to open one at a time, i do not know how to provide it multiple json files and use them, because the single file i have provided it in the index page was like this:

  var url = window.location.search.match(/url=([^&]+)/);
  if (url && url.length > 1) {
      url = decodeURIComponent(url[1]);
  } else {
      url = "http://localhost:1122/Json/Swagger-ui2.1.4V1.JSON";
  }

推荐答案

Swagger JSON 的基本结构应如下所示:

The basic structure of your Swagger JSON should look something like this:

{
"swagger": "2.0",
"info": {
    "title": "",
    "version": "version number here"
},
"basePath": "/",
"host": "host goes here",
"schemes": [
    "http"
],
"produces": [
    "application/json"
],
"paths": {},
"definitions": {}
}

paths 和 definitions 是您需要插入 API 支持的路径和描述响应对象的模型定义的地方.您可以动态填充这些对象.这样做的一种方法可能是为每个实体的路径和模型创建一个单独的文件.

The paths and definitions are where you need to insert the paths that your API supports and the model definitions describing your response objects. You can populate these objects dynamically. One way of doing this could be to have a separate file for each entity's paths and models.

假设您的 API 中的一个对象是汽车".

Let's say one of the objects in your API is a "car".

路径:

{
"paths": {
    "/cars": {
        "get": {
            "tags": [
                "Car"
            ],
            "summary": "Get all cars",
            "description": "Returns all of the cars.",
            "responses": {
                "200": {
                    "description": "An array of cars",
                    "schema": {
                        "type": "array",
                        "items": {
                            "$ref": "#/definitions/car"
                        }
                    }
                },
                "404": {
                    "description": "error fetching cars",
                    "schema": {
                        "$ref": "#/definitions/error"
                    }
                }
            }
        }
    }
}

型号:

{
"car": {
    "properties": {
        "_id": {
            "type": "string",
            "description": "car unique identifier"
        },
        "make": {
            "type": "string",
            "description": "Make of the car"
        },
        "model":{
            "type": "string",
            "description": "Model of the car."
        }
    }
}
}

然后您可以将其中的每一个都放在自己的文件中.当您启动服务器时，您可以获取这两个 JSON 对象，并将它们附加到您的基础 swagger 对象(paths 或 definitions)中的适当对象，并为该基础提供服务对象作为您的 Swagger JSON 对象.

You could then put each of these in their own files. When you start your server, you could grab these two JSON objects, and append them to the appropriate object in your base swagger object (either paths or definitions) and serve that base object as your Swagger JSON object.

您还可以通过仅在服务器启动时执行一次追加来进一步优化此功能(因为 API 文档在服务器运行时不会更改).然后，当服务 Swagger 文档"端点被命中时，您可以只返回在服务器启动时创建的缓存 Swagger JSON 对象.

You could also further optimize this by only doing the appending once when the server is started (since the API documentation will not change while the server is running). Then, when when the "serve Swagger docs" endpoint is hit, you can just return the cached Swagger JSON object that you created when the server was started.

serve Swagger docs"端点可以通过捕获对 /api-docs 的请求来拦截，如下所示:

The "serve Swagger docs" endpoint can be intercepted by catching a request to /api-docs like below:

app.get('/api-docs', function(req, res) {
  // return the created Swagger JSON object here
});

这篇关于在 swagger-ui 中使用多个 Json 文件的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！