Skip to content

Latest commit

 

History

History
95 lines (64 loc) · 3.17 KB

installation.md

File metadata and controls

95 lines (64 loc) · 3.17 KB
Raw

Installation

Distribution channels

NPM Registry

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.

Docker

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.

unpkg

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.