# express-jsdoc-swagger > Swagger OpenAPI 3.x generator Latest version **1.8.0** (published 2022-07-27) · MIT license · 0 weekly downloads ## Install ```sh npm install express-jsdoc-swagger pnpm add express-jsdoc-swagger yarn add express-jsdoc-swagger bun add express-jsdoc-swagger ``` ## Health **Score 25/100 (F)** — status: abandoned. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support. Negative: abandoned. ## Facts | | | |---|---| | Version | 1.8.0 | | Published | 2022-07-27 | | First published | 2020-06-11 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Node | >= 10.0.0 | | Dependencies | 6 | | Unpacked size | 72.5 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 224 | | Author | BRIKEV | | Maintainers | kevinccbsg, brikev, bri06 | | Keywords | swagger, swagger-generator, express, jsdoc, node, docs, documentation, swagger-ui, OpenAPI | ## Links - npm: https://www.npmjs.com/package/express-jsdoc-swagger - Repository: https://github.com/brikev/express-jsdoc-swagger - Homepage: https://brikev.github.io/express-jsdoc-swagger-docs/#/ - Issues: https://github.com/brikev/express-jsdoc-swagger/issues - npm.io page: https://npm.io/package/express-jsdoc-swagger ## Dependencies (6) - [glob](https://npm.io/package/glob.md) ^7.1.6 - [chalk](https://npm.io/package/chalk.md) ^4.1.0 - [merge](https://npm.io/package/merge.md) ^2.1.1 - [express](https://npm.io/package/express.md) ^4.17.1 - [doctrine](https://npm.io/package/doctrine.md) ^3.0.0 - [swagger-ui-express](https://npm.io/package/swagger-ui-express.md) ^4.3.0 ## Alternatives - [@cantoo/pdf-lib](https://npm.io/package/@cantoo/pdf-lib.md) — 297.9K weekly downloads - [datatables.net-buttons](https://npm.io/package/datatables.net-buttons.md) — 200.1K weekly downloads - [@ckeditor/ckeditor5-export-pdf](https://npm.io/package/@ckeditor/ckeditor5-export-pdf.md) — 167.0K weekly downloads - [scanbot-web-sdk](https://npm.io/package/scanbot-web-sdk.md) — 15.0K weekly downloads - [@syncfusion/ej2-angular-pdfviewer](https://npm.io/package/@syncfusion/ej2-angular-pdfviewer.md) — 8.8K weekly downloads ## Recent versions - 1.8.0 (latest) — 2022-07-27 - 1.7.0 — 2022-07-01 - 1.6.8 — 2022-05-18 - 1.6.7 — 2021-10-25 - 1.6.6 — 2021-09-09 - 1.6.5 — 2021-09-06 - 1.6.4 — 2021-08-09 - 1.6.3 — 2021-08-03 - 1.6.2 — 2021-06-02 - 1.6.1 — 2021-05-11 - 1.6.0 — 2021-04-18 - 1.5.0 — 2021-04-15 - 1.4.0 — 2021-04-12 - 1.3.2 — 2021-02-22 - 1.3.1 — 2021-01-21 - … 12 more at https://npm.io/package/express-jsdoc-swagger/versions ## README ![npm](https://img.shields.io/npm/v/express-jsdoc-swagger) ![Node.js Package](https://github.com/BRIKEV/express-jsdoc-swagger/workflows/Build/badge.svg) [![Known Vulnerabilities](https://snyk.io/test/github/BRIKEV/express-jsdoc-swagger/badge.svg)](https://snyk.io/test/github/BRIKEV/express-jsdoc-swagger) [![Maintainability](https://api.codeclimate.com/v1/badges/6d5565df0c9c10e75b59/maintainability)](https://codeclimate.com/github/BRIKEV/express-jsdoc-swagger/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/6d5565df0c9c10e75b59/test_coverage)](https://codeclimate.com/github/BRIKEV/express-jsdoc-swagger/test_coverage) ![License: MIT](https://img.shields.io/badge/License-MIT-green.svg) ![npm](https://img.shields.io/npm/dm/express-jsdoc-swagger) # express-jsdoc-swagger With this library, you can document your express endpoints using swagger [OpenAPI 3 Specification](https://swagger.io/specification/) without writing YAML or JSON. You can write comments similar to `jsdoc` on each endpoint, and the dependecy is going to create the swagger UI. ## Table of Contents 1. [Prerequisites](#Prerequisites) 2. [Installation](#Installation) 3. [Basic Usage](#Basic-Usage) 4. [Basic Examples](#Basic-Examples) - [Advanced examples](https://github.com/BRIKEV/express-jsdoc-swagger/tree/master/examples) - [Official docs](https://brikev.github.io/express-jsdoc-swagger-docs/#/) 5. [Validator](#Validator) 6. [VSCode extension](https://marketplace.visualstudio.com/items?itemName=brikev.express-jsdoc-swagger-snippets) ## Prerequisites This library assumes you are using: 1. [NodeJS](https://nodejs.org) 2. [Express.js](http://www.expressjs.com) ## Installation ``` npm i express-jsdoc-swagger ``` ## Basic Usage ```javascript // index.js file const express = require('express'); const expressJSDocSwagger = require('express-jsdoc-swagger'); const options = { info: { version: '1.0.0', title: 'Albums store', license: { name: 'MIT', }, }, security: { BasicAuth: { type: 'http', scheme: 'basic', }, }, // Base directory which we use to locate your JSDOC files baseDir: __dirname, // Glob pattern to find your jsdoc files (multiple patterns can be added in an array) filesPattern: './**/*.js', // URL where SwaggerUI will be rendered swaggerUIPath: '/api-docs', // Expose OpenAPI UI exposeSwaggerUI: true, // Expose Open API JSON Docs documentation in `apiDocsPath` path. exposeApiDocs: false, // Open API JSON Docs endpoint. apiDocsPath: '/v3/api-docs', // Set non-required fields as nullable by default notRequiredAsNullable: false, // You can customize your UI options. // you can extend swagger-ui-express config. You can checkout an example of this // in the `example/configuration/swaggerOptions.js` swaggerUiOptions: {}, // multiple option in case you want more that one instance multiple: true, }; const app = express(); const PORT = 3000; expressJSDocSwagger(app)(options); /** * GET /api/v1 * @summary This is the summary of the endpoint * @return {object} 200 - success response */ app.get('/api/v1', (req, res) => res.json({ success: true, })); app.listen(PORT, () => console.log(`Example app listening at http://localhost:${PORT}`)); ``` ## Basic Examples 1. Basic configuration options. ```javascript const options = { info: { version: '1.0.0', title: 'Albums store', license: { name: 'MIT', }, }, security: { BasicAuth: { type: 'http', scheme: 'basic', }, }, baseDir: __dirname, // Glob pattern to find your jsdoc files (multiple patterns can be added in an array) filesPattern: './**/*.js', }; ``` 2. Components definition ```javascript /** * A song type * @typedef {object} Song * @property {string} title.required - The title * @property {string} artist - The artist * @property {number} year - The year - double */ ``` 3. Endpoint which returns a `Songs` model array in the response. ```javascript /** * GET /api/v1/albums * @summary This is the summary of the endpoint * @tags album * @return {array} 200 - success response - application/json */ app.get('/api/v1/albums', (req, res) => ( res.json([{ title: 'abum 1', }]) )); ``` 3. Endpoint PUT with body and path params which returns a `Songs` model array in the response. ```javascript /** * PUT /api/v1/albums/{id} * @summary Update album * @tags album * @param {string} name.path - name param description * @param {Song} request.body.required - songs info * @return {array} 200 - success response - application/json */ app.put('/api/v1/albums/:id', (req, res) => ( res.json([{ title: 'abum 1', }]) )); ``` 4. Basic endpoint definition with tags, params and basic authentication ```javascript /** * GET /api/v1/album * @summary This is the summary of the endpoint * @security BasicAuth * @tags album * @param {string} name.query.required - name param description * @return {object} 200 - success response - application/json * @return {object} 400 - Bad request response */ app.get('/api/v1/album', (req, res) => ( res.json({ title: 'abum 1', }) )); ``` 5. Basic endpoint definition with code example for response body ```javascript /** * GET /api/v1/albums * @summary This is the summary of the endpoint * @tags album * @return {array} 200 - success response - application/json * @example response - 200 - success response example * [ * { * "title": "Bury the light", * "artist": "Casey Edwards ft. Victor Borba", * "year": 2020 * } * ] */ app.get('/api/v1/albums', (req, res) => ( res.json([{ title: 'track 1', }]) )); ``` You can find more examples [here](https://github.com/BRIKEV/express-jsdoc-swagger/tree/master/examples), or visit our [documentation](https://brikev.github.io/express-jsdoc-swagger-docs/#/). ## Validator We developed a new package works as a validator of your API endpoints and the documentation you create with this package. This package is [express-oas-validator](https://github.com/BRIKEV/express-oas-validator). **Example** Install using the node package registry: ``` npm install --save express-oas-validator ``` We have to wait until we have the full swagger schema to initiate the validator. ```js // validator.js const { init } = require('express-oas-validator'); const validators = instance => new Promise((resolve, reject) => { instance.on('finish', (swaggerDef) => { const { validateRequest, validateResponse } = init(swaggerDef); resolve({ validateRequest, validateResponse }); }); instance.on('error', (error) => { reject(error); }); }); module.exports = validators; ``` You can check out this also in our [example folder](https://github.com/BRIKEV/express-jsdoc-swagger/tree/master/examples/validator). ```js // index.js const express = require('express'); const expressJSDocSwagger = require('express-jsdoc-swagger'); const validator = require('./validator'); const options = { info: { version: '1.0.0', title: 'Albums store', license: { name: 'MIT', }, }, filesPattern: './**.js', baseDir: __dirname, }; const app = express(); const instance = expressJSDocSwagger(app)(options); const serverApp = async () => { const { validateRequest, validateResponse } = await validator(instance); app.use(express.urlencoded({ extended: true })); app.use(express.json()); /** * A song * @typedef {object} Song * @property {string} title.required - The title * @property {string} artist - The artist * @property {integer} year - The year */ /** * POST /api/v1/songs * @param {Song} request.body.required - song info * @return {object} 200 - song response */ app.post('/api/v1/songs', validateRequest(), (req, res) => res.send('You save a song!')); /** * POST /api/v1/name * @param {string} request.body.required - name body description * @return {object} 200 - song response */ app.post('/api/v1/name', (req, res, next) => { try { // Validate response validateResponse('Error string', req); return res.send('Hello World!'); } catch (error) { return next(error); } }); /** * GET /api/v1/authors * @summary This is the summary or description of the endpoint * @param {string} name.query.required - name param description - enum:type1,type2 * @param {array} license.query - name param description * @return {object} 200 - success response - application/json */ app.get('/api/v1/authors', validateRequest({ headers: false }), (req, res) => ( res.json([{ title: 'album 1', }]) )); // eslint-disable-next-line no-unused-vars app.use((err, req, res, next) => { res.status(err.status).json(err); }); return app; }; const PORT = process.env.PORT || 4000; serverApp() .then(app => app.listen(PORT, () => console.log(`Listening PORT: ${PORT}`) )) .catch((err) => { console.error(err); process.exit(1); }); ``` You can visit our [documentation](https://brikev.github.io/express-jsdoc-swagger-docs/#/validator). ## 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
💻
Faruk Aydın
💻
Dahlmo
💻
Carlos Ravelo
💻
Paul Ishenin
💻

Sam Bingner
💻
Alexander Staroselsky
💻
Joel Abrahamsson
💻
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! --- _Source: https://npm.io/package/express-jsdoc-swagger · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._