We publish two modules to npm: swagger-ui
and swagger-ui-dist
.
swagger-ui
is meant for consumption by JavaScript web projects that include module bundlers, such as Webpack, Browserify, and Rollup. Its main file exports Swagger-UI's main function, and the module also includes a namespaced stylesheet at swagger-ui/dist/swagger-ui.css
. Here's an example:
import SwaggerUI from 'swagger-ui'
// or use require, if you prefer
const SwaggerUI = require('swagger-ui')
SwaggerUI({
dom_id: '#myDomId'
})
In contrast, swagger-ui-dist
is meant for server-side projects that need assets to serve to clients. The module, when imported, includes an absolutePath
helper function that returns the absolute filesystem path to where the swagger-ui-dist
module is installed.
Note: we suggest using swagger-ui
when your tooling makes it possible, as swagger-ui-dist
will result in more code going across the wire.
The module's contents mirrors the dist
folder you see in the Git repository. The most useful file is 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 like so:
const express = require('express')
const pathToSwaggerUi = require('swagger-ui-dist').absolutePath()
const app = express()
app.use(express.static(pathToSwaggerUi))
app.listen(3000)
The module also exports SwaggerUIBundle
and SwaggerUIStandalonePreset
, so
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
const ui = SwaggerUIBundle({
url: "https://petstore.swagger.io/v2/swagger.json",
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
],
layout: "StandaloneLayout"
})
SwaggerUIBundle
is equivalent to SwaggerUI
.
You can pull a pre-built docker image of the swagger-ui directly from Docker Hub:
docker pull swaggerapi/swagger-ui
docker run -p 80:8080 swaggerapi/swagger-ui
Will start nginx with swagger-ui on port 80.
Or you can provide your own swagger.json on your host
docker run -p 80:8080 -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui
The base URL of the web application can be changed by specifying the BASE_URL
environment variable:
docker run -p 80:8080 -e BASE_URL=/swagger -e SWAGGER_JSON=/foo/swagger.json -v /bar:/foo swaggerapi/swagger-ui
This will serve Swagger UI at /swagger
instead of /
.
For more information on controlling Swagger UI through the Docker image, see the Docker section of the Configuration documentation.
You can embed Swagger-UI's code directly in your HTML by using unpkg's interface:
<script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<!-- `SwaggerUIBundle` is now available on the page -->
See unpkg's main page for more information on how to use unpkg.