npmpackage.info

express-jsdoc-swagger-extended

Swagger OpenAPI 3.x generator

1.3.5

MIT

JavaScript

63.68 kB

3,031 2.8

Installations

npm install express-jsdoc-swagger-extended

Developer Guide

BETA

Typescript

No

Module System

CommonJS

Min. Node Version

>= 10.0.0

Node Version

15.9.0

NPM Version

7.5.6 Score

Supply Chain

95.3

Quality

Maintenance

100

Vulnerability

98.2

License

Pull Requests

Open

1

Total

45

Closed

1

Merged

43

Issues

Open

0

Total

0

Closed

0

Releases

Unable to fetch releases

Contributors

Unable to fetch Contributors

View All 1 Contributors

Languages

JavaScript

JavaScript (100%)

Love this project? Help keep it running — sponsor us today! 🚀

Developer

meabed

Download Statistics

Total Downloads

3,031

Last Day

Last Week

Last Month

Last Year

484

GitHub Statistics

MIT License

2 Stars

245 Commits

2 Watchers

4 Branches

1 Contributors

Updated on Aug 24, 2024

Maintainers

Package Meta Information

Latest Version

1.3.5

Package Id

express-jsdoc-swagger-extended@1.3.5

Unpacked Size

63.68 kB

Size

20.58 kB

File Count

NPM Version

7.5.6

Node Version

15.9.0

Total Downloads

Cumulative downloads

Total Downloads

3,031

Last Day

Compared to previous day

Last Week

300%

Compared to previous week

Last Month

71.4%

Compared to previous month

Last Year

28.4%

484

Compared to previous year

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dependencies

chalk doctrine express glob merge swagger-ui-express

Dev Dependencies

@commitlint/cli @commitlint/config-conventional eslint eslint-config-airbnb-base eslint-plugin-import eslint-plugin-jest husky jest

npm npm

express-jsdoc-swagger

With this library, you can document your express endpoints using swagger OpenAPI 3 Specification without writing YAML or JSON. You can write jsdoc comments on each endpoint, and the library is going to create the swagger UI.

Prerequisites

This library assumes you are using:

Installation

npm i express-jsdoc-swagger

Usage

1const express = require('express');
2const expressJSDocSwagger = require('express-jsdoc-swagger');
3
4const options = {
5  info: {
6    version: '1.0.0',
7    title: 'Albums store',
8    license: {
9      name: 'MIT',
10    },
11  },
12  security: {
13    BasicAuth: {
14      type: 'http',
15      scheme: 'basic',
16    },
17  },
18  filesPattern: './**/*.js', // Glob pattern to find your jsdoc files (it supports arrays too ['./**/*.controller.js', './**/*.route.js'])
19  swaggerUIPath: '/your-url', // SwaggerUI will be render in this url. Default: '/api-docs'
20  baseDir: __dirname,
21  exposeSwaggerUI: true, // Expose OpenAPI UI. Default true
22  exposeApiDocs: false, // Expose Open API JSON Docs documentation in `apiDocsPath` path. Default false.
23  apiDocsPath: '/v3/api-docs', // Open API JSON Docs endpoint. Default value '/v3/api-docs'.
24};
25
26const app = express();
27const PORT = 3000;
28
29expressJSDocSwagger(app)(options);
30
31/**
32 * GET /api/v1
33 * @summary This is the summary or description of the endpoint
34 * @return {object} 200 - success response
35 */
36app.get('/api/v1', (req, res) => res.json({
37  success: true,
38}));
39
40app.listen(PORT, () => console.log(`Example app listening at http://localhost:${PORT}`));
41

Examples

Basic configuration

1const options = {
2  info: {
3    version: '1.0.0',
4    title: 'Albums store',
5    license: {
6      name: 'MIT',
7    },
8  },
9  security: {
10    BasicAuth: {
11      type: 'http',
12      scheme: 'basic',
13    },
14  },
15  filesPattern: './**/*.js', // Glob pattern to find your jsdoc files
16  baseDir: __dirname,
17};

Components definition

1/**
2 * A song type
3 * @typedef {object} Song
4 * @property {string} title.required - The title
5 * @property {string} artist - The artist
6 * @property {number} year - The year - double
7 */

Endpoint that returns a Songs model array

1/**
2 * GET /api/v1/albums
3 * @summary This is the summary or description of the endpoint
4 * @tags album
5 * @return {array<Song>} 200 - success response - application/json
6 */
7app.get('/api/v1/albums', (req, res) => (
8  res.json([{
9    title: 'abum 1',
10  }])
11));

Basic endpoint definition with tags, params and basic authentication

1/**
2 * GET /api/v1/album
3 * @summary This is the summary or description of the endpoint
4 * @security BasicAuth
5 * @tags album
6 * @param {string} name.query.required - name param description
7 * @return {object} 200 - success response - application/json
8 * @return {object} 400 - Bad request response
9 */
10app.get('/api/v1/album', (req, res) => (
11  res.json({
12    title: 'abum 1',
13  })
14));

Basic endpoint definition with code example for response body

1/**
2 * GET /api/v1/albums
3 * @summary This is the summary or description of the endpoint
4 * @tags album
5 * @return {array<Song>} 200 - success response - application/json
6 * @example response - 200 - success response example
7 * [
8 *   {
9 *     "title": "Bury the light",
10 *     "artist": "Casey Edwards ft. Victor Borba",
11 *     "year": 2020
12 *   }
13 * ]
14 */
15app.get('/api/v1/albums', (req, res) => (
16  res.json([{
17    title: 'track 1',
18  }])
19));

You can find more examples here, or visit our documentation.

Contributors ✨

_{Briam Martinez Escobar} 💻	_{Kevin Julián Martínez Escobar} 💻	_{Heung-yeon Oh} 💻	_{Sara Hernández} 💻	_{Josep Servat} 💻	_{Nick Dong} 💻	_{Aleksander Stós} 💻
_{Kjell Dankert} 💻	_juliendu11 💻	_{Mohamed Meabed} 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

No vulnerabilities found.

10

Dangerous-Workflow

Determines if the project's GitHub Action workflows avoid dangerous patterns.

10

Binary-Artifacts

Determines if the project has generated executable (binary) artifacts in the source repository.

10

License

Determines if the project has defined a license.

5

Pinned-Dependencies

Determines if the project has declared and pinned the dependencies of its build process.

0

Code-Review

Determines if the project requires human code review before pull requests (aka merge requests) are merged.

0

Maintained

Determines if the project is "actively maintained".

0

Token-Permissions

Determines if the project's workflows follow the principle of least privilege.

0

CII-Best-Practices

Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.

0

Security-Policy

Determines if the project has published a security policy.

0

Fuzzing

Determines if the project uses fuzzing.

0

Branch-Protection

Determines if the default and release branches are protected with GitHub's branch protection settings.

0

SAST

Determines if the project uses static code analysis.

0

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

Score

2.8

/10

Last Scanned on 2025-02-10

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