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:

1. NodeJS
2. Express.js

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

1. 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};

2. 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 */

3. 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));

4. 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));

5. 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!