Use multiple Json files in swagger-ui

Question

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";
  }

Answer 1

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": {}
}

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.

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

Path:

{
"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"
                    }
                }
            }
        }
    }
}

Model:

{
"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."
        }
    }
}
}

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.

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.

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
});