Security News
Nightmares on npm: How Two Malicious Packages Facilitate Data Theft and Destruction
Our threat research team breaks down two malicious npm packages designed to exploit developer trust, steal your data, and destroy data on your machine.
swagger-ui-express
Advanced tools
The swagger-ui-express npm package is used to serve auto-generated swagger-ui generated API docs from express, based on a swagger.json file. The package allows you to serve the Swagger UI bound to your Swagger document. This is helpful for creating API documentation that can be read and tested interactively via a browser.
Serve API Documentation
This feature serves the API documentation on a specified express route. The `swagger.json` contains the API definitions.
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
Custom CSS
This feature allows you to apply custom CSS to the Swagger UI to modify its appearance according to your preferences.
const options = {
customCss: '.swagger-ui .topbar { display: none }'
};
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));
Custom Site Title
This feature allows you to set a custom title for the API documentation page.
const options = {
customSiteTitle: 'My API Docs'
};
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));
Serve Swagger UI with Custom API Docs
This feature allows you to load your Swagger document from a YAML file instead of a JSON file, which some developers find more readable and easier to maintain.
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
const swaggerDocument = YAML.load('./swagger.yaml');
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
Redoc-express is similar to swagger-ui-express in that it serves API documentation using the express framework. However, it uses Redoc to generate the documentation, which offers a different look and feel and some different features compared to Swagger UI.
Fastify-swagger is designed for the Fastify framework rather than Express. It provides similar functionality to swagger-ui-express but is tailored to work with Fastify's unique plugin architecture.
Hapi-swagger is an npm package that provides Swagger UI integration for the Hapi.js framework. It is similar to swagger-ui-express but is specifically built to work within the Hapi ecosystem.
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.0.17
In app's package.json
"swagger-ui-express": "latest" // or desired version
Express setup app.js
const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
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
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));
By default the Swagger Explorer bar is hidden, to display it pass true as the second parameter to the setup function:
const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
var showExplorer = true;
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, showExplorer));
To pass custom options e.g. validatorUrl, to the SwaggerUi client pass an object as the third parameter:
const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
var showExplorer = true;
var options = {
validatorUrl : null
};
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, showExplorer, options));
To customize the style of the swagger page, you can pass custom CSS as the fourth parameter.
E.g. to hide the swagger header:
const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');
var showExplorer = false;
var options = {};
var customCss = '#header { display: none }';
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, showExplorer, options, customCss));
Install phantom npm install npm test
FAQs
Swagger UI Express
The npm package swagger-ui-express receives a total of 1,279,713 weekly downloads. As such, swagger-ui-express popularity was classified as popular.
We found that swagger-ui-express demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Our threat research team breaks down two malicious npm packages designed to exploit developer trust, steal your data, and destroy data on your machine.
Security News
A senior white house official is urging insurers to stop covering ransomware payments, indicating possible stricter regulations to deter cybercrime.
Security News
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.