Gathering detailed insights and metrics for swagger-ui-express
Gathering detailed insights and metrics for swagger-ui-express
Gathering detailed insights and metrics for swagger-ui-express
Gathering detailed insights and metrics for swagger-ui-express
@types/swagger-ui-express
TypeScript definitions for swagger-ui-express
express-swagger-generator
Generates swagger doc & ui based on express existing routes.
@pepperize/cdk-apigateway-swagger-ui
Add SwaggerUI to your AWS Apigateway RestApi
express-swaggerize-ui
Express middleware to display a swagger-ui 3 page
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.
npm install swagger-ui-express
Typescript
Module System
Min. Node Version
Node Version
NPM Version
52.1
Supply Chain
94.5
Quality
74.7
Maintenance
100
Vulnerability
99.6
License
HTML (54.02%)
JavaScript (38.96%)
CSS (7.02%)
Total Downloads
258,415,962
Last Day
314,342
Last Week
1,761,416
Last Month
7,775,017
Last Year
75,556,533
1,436 Stars
210 Commits
229 Forks
15 Watching
5 Branches
40 Contributors
Minified
Minified + Gzipped
Latest Version
5.0.1
Package Id
swagger-ui-express@5.0.1
Unpacked Size
23.40 kB
Size
6.94 kB
File Count
4
NPM Version
9.5.0
Node Version
18.15.0
Publised On
31 May 2024
Cumulative downloads
Total Downloads
Last day
-2.6%
314,342
Compared to previous day
Last week
-1.8%
1,761,416
Compared to previous week
Last month
6.8%
7,775,017
Compared to previous month
Last year
12.1%
75,556,533
Compared to previous year
1
1
Statements | Branches | Functions | Lines |
---|---|---|---|
This module allows you to serve auto-generated swagger-ui generated API docs from express, based on a swagger.json
file. The result is living documentation for your API hosted from your API server via a route.
Swagger version is pulled from npm module swagger-ui-dist. Please use a lock file or specify the version of swagger-ui-dist you want to ensure it is consistent across environments.
You may be also interested in:
Install using npm:
1$ npm install swagger-ui-express
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));
or if you are using Express router
1const router = require('express').Router(); 2const swaggerUi = require('swagger-ui-express'); 3const swaggerDocument = require('./swagger.json'); 4 5router.use('/api-docs', swaggerUi.serve); 6router.get('/api-docs', 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:
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));
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));
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));
For all the available options, refer to Swagger UI Configuration
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: '.swagger-ui .topbar { display: none }' 8}; 9 10app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));
You can also pass the url to a custom css file, the value must be the public url of the file and can be relative or absolute to the swagger path.
1const express = require('express'); 2const app = express(); 3const swaggerUi = require('swagger-ui-express'); 4const swaggerDocument = require('./swagger.json'); 5 6var options = { 7 customCssUrl: '/custom.css' 8}; 9 10app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));
You can also pass an array of css urls to load multiple css files.
1const express = require('express'); 2const app = express(); 3const swaggerUi = require('swagger-ui-express'); 4const swaggerDocument = require('./swagger.json'); 5 6var options = { 7 customCssUrl: [ 8 '/custom.css', 9 'https://example.com/other-custom.css' 10 ] 11}; 12 13app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));
If you would like to have full control over your HTML you can provide your own javascript file, value accepts absolute or relative path. Value must be the public url of the js file.
1const express = require('express'); 2const app = express(); 3const swaggerUi = require('swagger-ui-express'); 4const swaggerDocument = require('./swagger.json'); 5 6var options = { 7 customJs: '/custom.js' 8}; 9 10app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));
You can also pass an array of js urls to load multiple js files.
1const express = require('express'); 2const app = express(); 3const swaggerUi = require('swagger-ui-express'); 4const swaggerDocument = require('./swagger.json'); 5 6var options = { 7 customJs: [ 8 '/custom.js', 9 'https://example.com/other-custom.js' 10 ] 11}; 12 13app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));
It is also possible to add inline javascript, either as string or array of string.
1const express = require('express'); 2const app = express(); 3const swaggerUi = require('swagger-ui-express'); 4const swaggerDocument = require('./swagger.json'); 5 6var options = { 7 customJsStr: 'console.log("Hello World")' 8}; 9 10app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));
1const express = require('express'); 2const app = express(); 3const swaggerUi = require('swagger-ui-express'); 4const swaggerDocument = require('./swagger.json'); 5 6var options = { 7 customJsStr: [ 8 'console.log("Hello World")', 9 ` 10 var x = 1 11 console.log(x) 12 ` 13 ] 14}; 15 16app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, options));
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 'url' property to 'swaggerOptions' in the setup function.
1const express = require('express'); 2const app = express(); 3const swaggerUi = require('swagger-ui-express'); 4 5var options = { 6 swaggerOptions: { 7 url: 'http://petstore.swagger.io/v2/swagger.json' 8 } 9} 10 11app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(null, options));
To load multiple swagger documents from urls as a dropdown in the explorer bar, pass an array of object with name
and url
to 'urls' property to 'swaggerOptions' in the setup function.
1const express = require('express'); 2const app = express(); 3const swaggerUi = require('swagger-ui-express'); 4 5var options = { 6 explorer: true, 7 swaggerOptions: { 8 urls: [ 9 { 10 url: 'http://petstore.swagger.io/v2/swagger.json', 11 name: 'Spec1' 12 }, 13 { 14 url: 'http://petstore.swagger.io/v2/swagger.json', 15 name: 'Spec2' 16 } 17 ] 18 } 19} 20 21app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(null, options));
Make sure 'explorer' option is set to 'true' in your setup options for the dropdown to be visible.
To load your swagger specification yaml file you need to use a module able to convert yaml to json; for instance yaml
.
npm install yaml
1const express = require('express'); 2const app = express(); 3const swaggerUi = require('swagger-ui-express'); 4const fs = require("fs") 5const YAML = require('yaml') 6 7const file = fs.readFileSync('./swagger.yaml', 'utf8') 8const swaggerDocument = YAML.parse(file) 9 10app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
To dynamically set the host, or any other content, in the swagger file based on the incoming request object you may pass the json via the req object; to achieve this just do not pass the the swagger json to the setup function and it will look for swaggerDoc
in the req
object.
1const express = require('express'); 2const app = express(); 3const swaggerUi = require('swagger-ui-express'); 4const swaggerDocument = require('./swagger.json'); 5 6var options = {} 7 8app.use('/api-docs', function(req, res, next){ 9 swaggerDocument.host = req.get('host'); 10 req.swaggerDoc = swaggerDocument; 11 next(); 12}, swaggerUi.serveFiles(swaggerDocument, options), swaggerUi.setup());
To run 2 swagger ui instances with different swagger documents, use the serveFiles function instead of the serve function. The serveFiles function has the same signature as the setup function.
1const express = require('express'); 2const app = express(); 3const swaggerUi = require('swagger-ui-express'); 4const swaggerDocumentOne = require('./swagger-one.json'); 5const swaggerDocumentTwo = require('./swagger-two.json'); 6 7var options = {} 8 9app.use('/api-docs-one', swaggerUi.serveFiles(swaggerDocumentOne, options), swaggerUi.setup(swaggerDocumentOne)); 10 11app.use('/api-docs-two', swaggerUi.serveFiles(swaggerDocumentTwo, options), swaggerUi.setup(swaggerDocumentTwo)); 12 13app.use('/api-docs-dynamic', function(req, res, next){ 14 req.swaggerDoc = swaggerDocument; 15 next(); 16}, swaggerUi.serveFiles(), swaggerUi.setup());
To render a link to the swagger document for downloading within the swagger ui - then serve the swagger doc as an endpoint and use the url option to point to it:
1const express = require('express'); 2const app = express(); 3const swaggerUi = require('swagger-ui-express'); 4const swaggerDocument = require('./swagger.json'); 5 6var options = { 7 swaggerOptions: { 8 url: "/api-docs/swagger.json", 9 }, 10} 11app.get("/api-docs/swagger.json", (req, res) => res.json(swaggerDocument)); 12app.use('/api-docs', swaggerUi.serveFiles(null, options), swaggerUi.setup(null, options));
npm install
npm test
No vulnerabilities found.
Reason
no binaries found in the repo
Reason
0 existing vulnerabilities detected
Reason
license file detected
Details
Reason
Found 9/16 approved changesets -- score normalized to 5
Reason
2 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 1
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
security policy file not detected
Details
Reason
project is not fuzzed
Details
Reason
branch protection not enabled on development/release branches
Details
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
Score
Last Scanned on 2024-11-25
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More