94 lines
3.0 KiB
Markdown
94 lines
3.0 KiB
Markdown
# Installation
|
|
|
|
Swagger-UI is available
|
|
|
|
## 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:
|
|
|
|
```javascript
|
|
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:
|
|
|
|
```javascript
|
|
const express = require('express')
|
|
const pathToSwaggerUi = require('swagger-ui').absolutePath()
|
|
|
|
const app = express()
|
|
|
|
app.use(express.static(pathToSwaggerUi))
|
|
|
|
app.listen(3000)
|
|
```
|
|
|
|
The bundle also exports `SwaggerUIBundle` and `SwaggerUIStandalonePreset`, so
|
|
if you're in a JavaScript project that can't handle a tranditional npm module,
|
|
you could do something like this:
|
|
|
|
```js
|
|
var SwaggerUIBundle = require('swagger-ui-dist').SwaggerUIBundle
|
|
|
|
const ui = SwaggerUIBundle({
|
|
url: "http://petstore.swagger.io/v2/swagger.json",
|
|
dom_id: '#swagger-ui',
|
|
presets: [
|
|
SwaggerUIBundle.presets.apis,
|
|
SwaggerUIBundle.SwaggerUIStandalonePreset
|
|
]
|
|
layout: "StandaloneLayout"
|
|
})
|
|
```
|
|
|
|
### Docker Hub
|
|
|
|
You can pull a pre-built docker image of the swagger-ui directly from Dockerhub:
|
|
|
|
```
|
|
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 `/`.
|
|
|
|
### unpkg
|
|
|
|
You can embed Swagger-UI's code directly in your HTML by using unkpg's interface:
|
|
|
|
```html
|
|
<script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js">
|
|
<!-- `SwaggerUIBundle` is now available on the page -->
|
|
```
|
|
|
|
See [unpkg's main page](https://unpkg.com/) for more information on how to use unpkg.
|