theneo-doc-generator

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. Installation
2. Basic Usage
3. Basic Examples

Installation

npm i theneo-doc-generator

Basic Usage

1// index.js file
2const express = require('express');
3const theneoDocGenerator = require('theneo-doc-generator');
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
24  // Get get the api key from the user settings in theneo dashboard
25  apiKey: '<Api-Key>',
26
27  // can get api key from project settings
28  projectSlug: '<Project-slug>',
29
30  // merge => merge imported sections, endpoints => import only endpoints no sections will be created
31  importOptions: 'overwrite',
32
33  // Directory where the generated open api spec will be stored shouldn't be watched by nodemon/pm2
34  directory: './uploads',
35};
36
37
38
39theneoDocGenerator(options);
40

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
19  // Get get the api key from the user settings in theneo dashboard
20  apiKey: "<Api-Key>",
21
22  // can get api key from project settings
23  projectSlug: "<Project-slug>",
24
25  // merge => merge imported sections, endpoints => import only endpoints no sections will be created
26  importOptions: "overwrite",
27
28  // Directory where the generated open api spec will be stored shouldn't be watched by nodemon/pm2
29  directory: "./uploads",
30};

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    {
10      title: "abum 1",
11    },
12  ])
13);

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    {
12      title: "abum 1",
13    },
14  ])
15);

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    {
18      title: "track 1",
19    },
20  ])
21);