swagger-ui-express-context v2.1.3
Swagger UI Express
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-context": "latest" // or desired version
Express setup app.js
const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express-context');
const swaggerDocument = require('./swagger.json');
app.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:
// Initialize swagger-jsdoc -> returns validated swagger spec in json format
const swaggerSpec = swaggerJSDoc(options);
app.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:
const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express-context');
const swaggerDocument = require('./swagger.json');
var options = {
explorer : true
};
app.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:
const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express-context');
const swaggerDocument = require('./swagger.json');
var options = {
swaggerOptions: {
validatorUrl : null
}
};
app.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:
const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express-context');
const swaggerDocument = require('./swagger.json');
var options = {
customCss: '#header { display: none }'
};
app.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.
const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express-context');
const swaggerDocument = require('./swagger.json');
var options = {
swaggerUrl: 'http://petstore.swagger.io/v2/swagger.json'
}
app.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
const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express-context');
const YAML = require('yamljs');
const swaggerDocument = YAML.load('./swagger.yaml');
app.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
Reverse proxy povisions
Base path for the swagger options is set based on the x-original-uri
header passed by the nginx setting in front of the application. We're running node applications in Kubernetes with an ingress controller (nginx-ingress-controller) providing url rewriting. This poses a unique challenge: the application api endpoints are mapped correctly (internally application listens on the /
context), the Swagger UI renders properly, but once you try to invoke any endpoint through the Swagger UI, you end up hitting the root context, not the ingress defined context. The simple change I've introduced allows the dynamic remapping. Hopefully, one day it will make it into the upstream project.