How to merge several Swagger (v. 1.2) JSON files?

Question

Having a master JSON file

{"swaggerVersion":"1.2",
 "apiVersion":"1.0",
 "apis":[{"path":"/api1"},{"path":"/api2"},{"path":"/api3"},{"path":"/api4"}]}

and JSON files for each of the 4 APIs, which working well with the Swagger library each.

But when I tried to place it all into one JSON file like

 {"swaggerVersion":"1.2",
  "apiVersion":"1.0",
  "apis":[{<api1 json file contents>},{<api2 json file contents>},{<api3 json file contents>},{<api4 json file contents>}]}

it didn't work.

What is proper way to do merge several Swagger v. 1.2 files into a single file?

Answer 1

According to the Swagger 1.2 Specification you just cannot do that.

The "master" JSON file (as you called it) is the Resource Listing of a Swagger API, which just contains an "inventory of the available resources".

The "apis" property of this JSON document is expected be an array of Resource Objects with a specific structure:

{
  "path": "/pets",
  "description": "Operations about pets."
}

Quoting the API Declaration section of the spec:

The API Declaration provides information about an API exposed on a resource. There should be one file per Resource described. The file MUST be served in the URL described by the path field.

Answer 2

Take a look at the demo application to view all service documentations at a single location: https://github.com/varghgeorge/microservices-single-swagger

Repo shows how to create a springboot application which will serve as a single place for all your springfox/swagger documentations.

Swagger documentation from different services/locations can be configured in this server using yaml config. Details are on the github location.