How to organise/build a Swagger UI interface for a directory which contains many Swagger definition .json/.yml files

Question

I am trying to document, via Swagger UI, for internal company consumption, existing API services which are developed in a vendor product (WSO2 ESB). The vendor product does not support swagger. I plan to programmatically inspect/process the source code for my API services (written in the vendor product) and generate a directory/folder/library of swagger definition files in .json or .yml format. That is fine, I can do that.

Each of these api defintion files will render nicely in swagger UI, I am looking at using https://www.npmjs.com/package/swagger-ui.

My issue is I will end up with around 100 of these API definition files, I would like to provide some overarching interface/page which lists all of the API's and then takes the user to Swagger UI with the particular API definition loaded when the user clicks on one of the links. This is equivalent to opening my local swagger-ui and manually typing/copying in the path to the relevant API definition. This works fine if I do it manually, I just don't want the user to have to do this manually. How would they know what API definition url's exist and why make them manually type/copy them in.

I can't see how to pass a "apiDefintionToLoad" parameter into Swagger-ui, I guess I will either find one or change the source to support that. Does this exist?

Is there a better solution, either to develop myself or using an existing package or solution? I prefer node based solutions, java is also ok.

Am I going at this wrong?

Thanks, Matt.

Answer 1

what you're looking for can be done very easily with the basic Swagger-ui tool.

Essentially what you have is a list of many swagger definitions. I'm guessing that you want to let the user click a button or a link, or choose a definition from a drop-down to select the API to view. Once that's done, you can do the following:

• Let the user choose an API definition to show. You can get this easily from adding a HTML element to your index.html and trigging some javascript after selecting

• A single swagger-ui container can be reloaded and reused. Get the URL to the swagger definition from the first step and supply it to the swagger-ui object, which is typically done like this:

  window.swaggerUi.updateSwaggerUi({url: 'http://your.spec.com/swagger.yaml'})

Now the container will reload with the spec you've specified.

Answer 2

Swagger UI 3.0.19 natively supports multiple specs via the urls parameter. When urls is used, the top bar displays a drop-down list of specs instead of an input box.

Usage

Edit dist\index.html and change

url: "http://petstore.swagger.io/v2/swagger.json",

to

urls: [
   {name: "petstore",  url: "http://petstore.swagger.io/v2/swagger.json"},
   {name: "instagram", url: "https://api.apis.guru/v2/specs/instagram.com/1.0.0/swagger.yaml"}
],
"urls.primaryName": "petstore",  // default spec

Now your Swagger UI top bar looks like this: