Swagger UI Express

NOTE: This is a fork of swagger-ui-express which only removes .map files from package.

Adds middleware to your express app to serve the Swagger UI bound to your Swagger document. This acts as living documentation for your API hosted from within your app.

Updated to Swagger 3.4.4

Usage

In app's package.json

"swagger-ui-express": "latest" // or desired version

Express setup app.js

1const express = require('express');
2const app = express();
3const swaggerUi = require('swagger-ui-express');
4const swaggerDocument = require('./swagger.json');
5
6app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

Open http://<app_host>:<app_port>/api-docs in your browser to view the documentation.

If you want to set up routing based on the swagger document checkout swagger-express-router

swagger-jsdoc

If you are using swagger-jsdoc simply pass the swaggerSpec into the setup function:

1// Initialize swagger-jsdoc -> returns validated swagger spec in json format
2const swaggerSpec = swaggerJSDoc(options);
3
4app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

Swagger Explorer

By default the Swagger Explorer bar is hidden, to display it pass true as the 'explorer' property of the options to the setup function:

1const express = require('express');
2const app = express();
3const swaggerUi = require('swagger-ui-express');
4const swaggerDocument = require('./swagger.json');
5
6var options = {
7  explorer : true
8};
9
10app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));

Custom swagger options

To pass custom options e.g. validatorUrl, to the SwaggerUi client pass an object as the 'swaggerOptions' property of the options to the setup function:

1const express = require('express');
2const app = express();
3const swaggerUi = require('swagger-ui-express');
4const swaggerDocument = require('./swagger.json');
5
6var options = {
7	swaggerOptions: {
8    validatorUrl : null
9  }
10};
11
12app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));

Custom CSS styles

To customize the style of the swagger page, you can pass custom CSS as the 'customCss' property of the options to the setup function.

E.g. to hide the swagger header:

1const express = require('express');
2const app = express();
3const swaggerUi = require('swagger-ui-express');
4const swaggerDocument = require('./swagger.json');
5
6var options = {
7  customCss: '#header { display: none }'
8};
9
10app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));

Load swagger from url

To load your swagger from a url instead of injecting the document, pass null as the first parameter, and pass the relative or absolute URL as the 'swaggerUrl' property of the options to the setup function.

1const express = require('express');
2const app = express();
3const swaggerUi = require('swagger-ui-express');
4
5const swaggerDocument = require('./swagger.json');
6
7var options = {
8  swaggerUrl: 'http://petstore.swagger.io/v2/swagger.json'
9}
10
11app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(null, options));

Load swagger from yaml file

To load your swagger specification yaml file you need to use a module able to convert yaml to json ; for instance yamljs.

npm install --save yamljs

1const express = require('express');
2const app = express();
3const swaggerUi = require('swagger-ui-express');
4const YAML = require('yamljs');
5const swaggerDocument = YAML.load('./swagger.yaml');
6
7app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

Requirements

• Node v0.10.32 or above
• Express 4 or above

Testing

Install phantom npm install npm test