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 comments similar to jsdoc on each endpoint, and the dependecy is going to create the swagger UI.

Table of Contents

1. Prerequisites
2. Installation
3. Basic Usage
4. Basic Examples
   • Advanced examples
   • Official docs
5. Validator
6. VSCode extension

Prerequisites

This library assumes you are using:

1. NodeJS
2. Express.js

Installation

npm i express-jsdoc-swagger

Basic Usage

1// index.js file
2const express = require('express');
3const expressJSDocSwagger = require('express-jsdoc-swagger');
4
5const options = {
6  info: {
7    version: '1.0.0',
8    title: 'Albums store',
9    license: {
10      name: 'MIT',
11    },
12  },
13  security: {
14    BasicAuth: {
15      type: 'http',
16      scheme: 'basic',
17    },
18  },
19  // Base directory which we use to locate your JSDOC files
20  baseDir: __dirname,
21  // Glob pattern to find your jsdoc files (multiple patterns can be added in an array)
22  filesPattern: './**/*.js',
23  // URL where SwaggerUI will be rendered
24  swaggerUIPath: '/api-docs',
25  // Expose OpenAPI UI
26  exposeSwaggerUI: true,
27  // Expose Open API JSON Docs documentation in `apiDocsPath` path.
28  exposeApiDocs: false,
29  // Open API JSON Docs endpoint.
30  apiDocsPath: '/v3/api-docs',
31  // Set non-required fields as nullable by default
32  notRequiredAsNullable: false,
33  // You can customize your UI options.
34  // you can extend swagger-ui-express config. You can checkout an example of this
35  // in the `example/configuration/swaggerOptions.js`
36  swaggerUiOptions: {},
37  // multiple option in case you want more that one instance
38  multiple: true,
39};
40
41const app = express();
42const PORT = 3000;
43
44expressJSDocSwagger(app)(options);
45
46/**
47 * GET /api/v1
48 * @summary This is the summary of the endpoint
49 * @return {object} 200 - success response
50 */
51app.get('/api/v1', (req, res) => res.json({
52  success: true,
53}));
54
55app.listen(PORT, () => console.log(`Example app listening at http://localhost:${PORT}`));

Basic Examples

1. Basic configuration options.

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  baseDir: __dirname,
16  // Glob pattern to find your jsdoc files (multiple patterns can be added in an array)
17  filesPattern: './**/*.js',
18};

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 which returns a Songs model array in the response.

1/**
2 * GET /api/v1/albums
3 * @summary This is the summary 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));

3. Endpoint PUT with body and path params which returns a Songs model array in the response.

1/**
2 * PUT /api/v1/albums/{id}
3 * @summary Update album
4 * @tags album
5 * @param {string} name.path - name param description
6 * @param {Song} request.body.required - songs info
7 * @return {array<Song>} 200 - success response - application/json
8 */
9app.put('/api/v1/albums/:id', (req, res) => (
10  res.json([{
11    title: 'abum 1',
12  }])
13));

4. Basic endpoint definition with tags, params and basic authentication

1/**
2 * GET /api/v1/album
3 * @summary This is the summary 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 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.

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.

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.

1// validator.js
2const { init } = require('express-oas-validator');
3
4const validators = instance => new Promise((resolve, reject) => {
5  instance.on('finish', (swaggerDef) => {
6    const { validateRequest, validateResponse } = init(swaggerDef);
7    resolve({ validateRequest, validateResponse });
8  });
9
10  instance.on('error', (error) => {
11    reject(error);
12  });
13});
14
15module.exports = validators;
16

You can check out this also in our example folder.

1// index.js
2const express = require('express');
3const expressJSDocSwagger = require('express-jsdoc-swagger');
4const validator = require('./validator');
5
6const options = {
7  info: {
8    version: '1.0.0',
9    title: 'Albums store',
10    license: {
11      name: 'MIT',
12    },
13  },
14  filesPattern: './**.js',
15  baseDir: __dirname,
16};
17
18const app = express();
19const instance = expressJSDocSwagger(app)(options);
20
21const serverApp = async () => {
22  const { validateRequest, validateResponse } = await validator(instance);
23  app.use(express.urlencoded({ extended: true }));
24  app.use(express.json());
25  /**
26   * A song
27   * @typedef {object} Song
28   * @property {string} title.required - The title
29   * @property {string} artist - The artist
30   * @property {integer} year - The year
31   */
32
33  /**
34   * POST /api/v1/songs
35   * @param {Song} request.body.required - song info
36   * @return {object} 200 - song response
37   */
38  app.post('/api/v1/songs', validateRequest(), (req, res) => res.send('You save a song!'));
39
40  /**
41   * POST /api/v1/name
42   * @param {string} request.body.required - name body description
43   * @return {object} 200 - song response
44   */
45  app.post('/api/v1/name', (req, res, next) => {
46    try {
47      // Validate response
48      validateResponse('Error string', req);
49      return res.send('Hello World!');
50    } catch (error) {
51      return next(error);
52    }
53  });
54
55  /**
56   * GET /api/v1/authors
57   * @summary This is the summary or description of the endpoint
58   * @param {string} name.query.required - name param description - enum:type1,type2
59   * @param {array<string>} license.query - name param description
60   * @return {object} 200 - success response - application/json
61   */
62  app.get('/api/v1/authors', validateRequest({ headers: false }), (req, res) => (
63    res.json([{
64      title: 'album 1',
65    }])
66  ));
67
68  // eslint-disable-next-line no-unused-vars
69  app.use((err, req, res, next) => {
70    res.status(err.status).json(err);
71  });
72
73  return app;
74};
75
76const PORT = process.env.PORT || 4000;
77
78serverApp()
79  .then(app => 
80    app.listen(PORT, () =>
81      console.log(`Listening PORT: ${PORT}`)
82    ))
83  .catch((err) => {
84    console.error(err);
85    process.exit(1);
86  });

You can 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 💻	Faruk Aydın 💻	Dahlmo 💻	Carlos Ravelo 💻	Paul Ishenin 💻
Sam Bingner 💻	Alexander Staroselsky 💻	Joel Abrahamsson 💻

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