haegemonia76
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-swaggerUsage
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',
},
},
filesPattern: ['./**/*.js'], // Glob pattern to find your jsdoc files
swaggerUIPath: '/your-url', // SwaggerUI will be render in this url. Default: '/api-docs'
baseDir: __dirname,
};
const app = express();
const PORT = 3000;
expressJSDocSwagger(app)(options);
/**
* GET /api/v1
* @summary This is the summary or description 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}`));
Examples
Basic configuration
const options = { info: { version: '1.0.0', title: 'Albums store', license: { name: 'MIT', }, }, security: { BasicAuth: { type: 'http', scheme: 'basic', }, }, filesPattern: ['./**/*.js'], // Glob pattern to find your jsdoc files baseDir: __dirname, };Components definition
/** * A song type * @typedef {object} Song * @property {string} title.required - The title * @property {string} artist - The artist * @property {number} year - The year - double */Endpoint that returns a
Songsmodel array/** * GET /api/v1/albums * @summary This is the summary or description of the endpoint * @tags album * @return {array<Song>} 200 - success response - application/json */ app.get('/api/v1/albums', (req, res) => ( res.json([{ title: 'abum 1', }]) ));Basic endpoint definition with tags, params and basic authentication
/** * GET /api/v1/album * @summary This is the summary or description 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', }) ));
You can find more examples here, or visit our documentation.
Contributors ✨
 Briam Martinez Escobar 💻 |
 Kevin Julián Martínez Escobar 💻 |
 Heung-yeon Oh 💻 |
This project follows the all-contributors specification. Contributions of any kind welcome!