CODEWITHSUNDEEP
swagger-ui
zag2010
zag2010

Reputation: 509

Swagger UI with Multiple Urls

I saw in the swagger ui documentation that you can provide a urls parameter which is:

An array of API definition objects ({url: "", name: ""}) used by Topbar plugin. When used and Topbar plugin is enabled, the url parameter will not be parsed. Names and URLs must be unique among all items in this array, since they're used as identifiers.

I was hoping that this will give me a selector from which I can chose which of my yaml files to process. Unfortunately, it doesn't seem to do anything.

Here is my code:

window.onload = function() {
  // Build a system
  const ui = SwaggerUIBundle({
    urls: [
      {
        url: "http://test.dev/documentation/microservices/microservices.yaml",
        name: "All Microservices"
      },
      {
        url: "http://test.dev/documentation/microservices/plans.yaml",
        name: "Plans"
      },
    ],
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  })

  window.ui = ui
}

I'd also like to set the primaryName to All Microservices.

Any ideas on where I'm going wrong?

Upvotes: 29

Views: 33250

Answers (4)

Ante Novokmet
Ante Novokmet

Reputation: 397

I also had this issue, No API definition provided. when using the urls option. I was confused about the TopBar plugin. Including the swagger-ui-standalone-preset as shown here solved it:

<script src="https://unpkg.com/[email protected]/swagger-ui-bundle.js" crossorigin></script>
<!-- Using StandalonePreset will render TopBar and ValidatorBadge as well. -->
<script src="https://unpkg.com/[email protected]/swagger-ui-standalone-preset.js" crossorigin></script>

...

<script>
  window.onload = () => {
    window.ui = SwaggerUIBundle({
      url: 'https://petstore3.swagger.io/api/v3/openapi.json',
      dom_id: '#swagger-ui',
      presets: [
        SwaggerUIBundle.presets.apis,
        SwaggerUIStandalonePreset
      ],
      layout: "StandaloneLayout",
    });
  };
</script>

Upvotes: 0

Hannan
Hannan

Reputation: 125

This is how you can List the Swagger endpoints that you want to be documented through the swagger-ui

The first parameter is the path (absolute or relative to the UI host) to the corresponding endpoint and the second is a title that will be displayed in the document selector

Rswag::Ui.configure do |c|

  c.swagger_endpoint '/api-docs/v1/swagger.json', 'API V1 Docs'
  c.swagger_endpoint '/api-docs/client/swagger.json', 'API client Docs'
  c.swagger_endpoint '/api-docs/participant/swagger.json', 'API Participant Docs'
end

NOTE: If you're using rspec-api to expose Swagger files (under swagger_root) as JSON or YAML endpoints, then the list above should correspond to the relative paths for those endpoints

Upvotes: 0

Aaron Lozier
Aaron Lozier

Reputation: 320

If the above solution works for you, great! But based on my own experience and research, it's not so simple for a lot of us.

The Swagger UI Documentation seems to suggest the urls parameter will do exactly what we're all looking for, but there's a little caveat: "used by Topbar plugin". What's the "Topbar plugin?" This is, in fact, the only mention of such a plugin in the entire documentation!

Burrowing deeper into the rabbit hole, one might discover as I did that this is a part of the "Standalone Layout." This led me to the discovery of the SwaggerUIBundle object, which is part of the swagger-ui-dist module, which is somehow different from the swagger-ui module, and yet really, really similar. Am I crazy, or is this all insanely convoluted?

For those who would rather stop digging deeper down the rabbit hole, I began digging into the source code instead and eventually uncovered the undocumented features which allow us to do exactly what we need - swap out the swagger yaml file used by the UI rendering. It's actually so simple, once you know what to do:

const ui = SwaggerUI({
    url: 'https://example.com/swagger-v1.yaml',
    dom_id: '#swaggerDocs'
});

ui.specActions.updateUrl('https://example.com/swagger-v2.yaml');
ui.specActions.download('https://example.com/swagger-v2.yaml');

With these methods at your disposal, you can build any UI you'd like to give your users the ability to browse through different swagger definitions.

Upvotes: 4

Helen
Helen

Reputation: 97991

The urls configuration option is supported in Swagger UI 3.0.18 and later.

You can use it instead of url like this:

window.onload = function() {
  // Build a system
  const ui = SwaggerUIBundle({
    urls: [
      {url: "https://path/to/api1.yaml", name: "API One"},
      {url: "https://path/to/api2.yaml", name: "API Two"},
    ],
    "urls.primaryName": "API Two"  // default document (if other than the first)
    ...
  })

Result:

"Select a definition" dropdown in Swagger UI

Upvotes: 40

Related Questions