What is the difference between SwaggerUIBundle, and SwaggerUi

Question

I've seen both in samples I've found and haven't seen how they are different. Is the bundle needed if you are using this in an HTML page only (not using a single-page-app) or is that the one to use if you are using a single-page-app?

The Swagger UI docs discuss two ways to deploy swagger-ui.

• traditional npm - swagger-ui

• dependency-free module - swagger-ui-dist

I've seen examples like this one where SwaggerUIBundle is used on what appears to be a web page hosted in tomcat (python, or some other web server) example.

<script src="./swagger-ui-bundle.js"> </script>
// later
<script>
window.onload = function() {
  // Build a system
  const ui = SwaggerUIBundle({
    url: "https://petstore.swagger.io/v2/swagger.json",

But also seen examples like this one that use SwaggerUi.

window.swaggerUi = new SwaggerUi({
  url: "http://petstore.swagger.wordnik.com/api/api-docs",
  dom_id: "swagger-ui-container",

A search returns things like:

• swagger-ui-bundle.js - https://github.com/swagger-api/swagger-ui/issues/3978

• SwaggerUi - https://stackoverflow.com/a/29497301/3281336

• SwaggerUIBundle - https://github.com/swagger-api/swagger-ui/wiki/FAQ

Answer 1

This page Installation Distribution Channels NPM Registry says:

SwaggerUIBundle is equivalent to SwaggerUI.

But then explains the differences. So they are functionally equivalent but the one you choose will depend on how your webserver/website is serving up the swagger user interface page.

The first example with const ui = SwaggerUIBundle(... is for Swagger UI 3.x, which is the current version of Swagger UI. The second example with window.swaggerUi = new SwaggerUi(... is for the old Swagger UI 2.x. Credit @Helen for this info in this answer)

For more details read on...

SwaggerUI Explained

SwaggerUI is used in apps that can import npm modules. This includes React, Angular or other single-page-apps (SPAs) that include the webpack-like tooling to package the resources for delivery to the browser.

The webpage says this:

import SwaggerUI from 'swagger-ui'

swagger-ui is meant for consumption by JavaScript web projects that include module bundlers, such as Webpack, Browserify, and Rollup.

Here's an example of using the npm intalled module swagger-ui.

import SwaggerUI from 'swagger-ui'
// or use require, if you prefer
const SwaggerUI = require('swagger-ui')
SwaggerUI({
  dom_id: '#myDomId'
})

SwaggerUIBundle Explained

SwaggerUIBundle is used when your app does not support importing npm modules (e.g., a java webapp).

The swagger user interface can be loaded by using the swagger index.html page (included in the swagger-ui-bundle) or by your own personal html page that includes the bundle file and uses the Javascript shown below:

The following comes from the website and is edited to highlight my above statements:

The [...] dist folder [has] swagger-ui-bundle.js, which is a build of Swagger-UI that includes all the code it needs to run in one file. The folder also has an index.html asset, to make it easy to serve Swagger-UI...

An example of how to use the SwaggerUIBundle is:

var SwaggerUIBundle = require('swagger-ui-dist').SwaggerUIBundle
const ui = SwaggerUIBundle({
    url: "https://petstore.swagger.io/v2/swagger.json",
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIBundle.SwaggerUIStandalonePreset
    ],
    layout: "StandaloneLayout"
  })

The SwaggerUIBundle example is confusing

It is confusing because it says:

if you're in a JavaScript project that can't handle a traditional npm module, you could do something like this:

var SwaggerUIBundle = require('swagger-ui-dist').SwaggerUIBundle

which uses require() which is an npm module way of including the bundle.

A less confusing way to explain this would be to say:

If you are using Swagger in a non-module environment then you need to somehow get the swagger bundle javascript loaded into the browser page and then use the SwaggerUIBundle as shown below to make the swagger user interface render at the dom_id specified (in the example below it is swagger-ui).

const ui = SwaggerUIBundle({
    url: "https://petstore.swagger.io/v2/swagger.json",
    dom_id: '#swagger-ui',
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIBundle.SwaggerUIStandalonePreset
    ],
    layout: "StandaloneLayout"
  })

The way you load the swagger-ui-bundle onto your page will depend on the technologies you are using. If you want you can load the page using a <script src="bundle.js"></script>. See https://github.com/swagger-api/swagger-ui/blob/master/dist/index.html (which is in swagger-ui/dist/index.html).

If you are in a NodeJS express application you could load the swagger bundle onto the page using:

var SwaggerUIBundle = require('swagger-ui-dist').SwaggerUIBundle

How you get the swagger bundle javscript onto the page is up to you.