How to merge swagger multiple files in single swagger doc file?

Question

I have different swagger files for multiple APIs, like swagger1.json for OpenStack API, swagger2.json for Users API etc and I was trying to merge these all swagger files in one single file using remote $ref method.

Here is swagger1.json file for OpenStack api

{
    "stacks": {
        "get": {
            "tags": [
                "openstack"
            ],
            "summary": "Returns stacks from OpenStack",
            "description": "Returns all stacks from the OpenStack based on tenantId.",
            "consumes": [
                "application/json"
            ],
            "produces": [
                "application/json"
            ],
            "parameters": [
                {
                    "in": "query",
                    "type": "string",
                    "name": "tenantId",
                    "description": "search stacks for tenantId from OpenStack",
                    "required": false
                }
            ],
            "responses": {
                "200": {
                    "description": "OK"
                },
                "400": {
                    "description": "Unknown Error"
                },
                "401": {
                    "description": "Unauthorized"
                }
            }
        }
    }

}

And this is the swagger-merge.json where I want to add multiple swagger doc file using remote reference.

{
"swagger": "2.0",
"info": {
    "description": "something here",
    "version": "v0.7.0",
    "title": "The API Gateway",
    "contact": {
        "email": "dp@gmail.com"
    }
},
"host": "localhost",
"port":"9191",
"basePath": "/api/openstack",
"tags": [
    {
        "name": "OpenStackApi",
        "description": "Get stacks and running instance form OpenStack"
    }
],
"schemes": [
    "https"
],
"paths": {
    "$ref": "./swagger1.json#/stacks"
}

}

This isn't working for me. I am not able to see API methods I have written inside swagger1.json file. I have upload swaggerUI output. Any idea about what I am doing wrong and how can I solve this issue?

Answer 1

You can't $ref the whole contents of paths , you can only refer individual path items:

"paths": {
   "/stacks": {    <--- endpoint path
     "$ref": "./swagger1.json#/stacks"
   }
}