npm Node.js Package Known Vulnerabilities Maintainability Test Coverage License: MIT npm
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.
This library assumes you are using:
npm i express-jsdoc-swagger
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 (it supports arrays too ['./**/*.controller.js', './**/*.route.js']) swaggerUIPath: '/your-url', // SwaggerUI will be render in this url. Default: '/api-docs' baseDir: __dirname, exposeSwaggerUI: true, // Expose OpenAPI UI. Default true exposeApiDocs: false, // Expose Open API JSON Docs documentation in `apiDocsPath` path. Default false. apiDocsPath: '/v3/api-docs', // Open API JSON Docs endpoint. Default value '/v3/api-docs'. }; 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}`));
- 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', }) ));
- Basic endpoint definition with code example for response body
/** * GET /api/v1/albums * @summary This is the summary or description of the endpoint * @tags album * @return {array<Song>} 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, or visit our documentation.
This project follows the all-contributors specification. Contributions of any kind welcome!