swagger-jsdoc setup in Express - Mini Project: Build & Apply

Setup swagger-jsdoc in an Express App

📖 Scenario: You are building a simple Express server and want to add automatic API documentation using swagger-jsdoc.This helps developers understand your API endpoints easily.

🎯 Goal: Set up swagger-jsdoc in your Express app to generate API documentation from JSDoc comments.

📋 What You'll Learn

Create a basic Express app with a single route

Add swagger-jsdoc configuration with API info and path to API files

Generate swagger specification using swagger-jsdoc

Serve the swagger JSON at a route

💡 Why This Matters

🌍 Real World

APIs often need clear documentation so other developers can understand and use them easily. swagger-jsdoc helps generate this documentation automatically from code comments.

💼 Career

Knowing how to set up swagger-jsdoc is useful for backend developers working with Node.js and Express to create well-documented APIs.

1

Create a basic Express app with one route

Create an Express app by importing express, then create an app instance called app. Add a GET route at /hello that sends the text 'Hello World'.

Express

const express = require('express');
const app = express();

// Your code here

Hint

Use require('express') to import Express and app.get to create a route.

2

Add swagger-jsdoc configuration object

Create a constant called swaggerOptions that is an object with a definition property. Inside definition, add openapi set to '3.0.0' and info with title as 'My API' and version as '1.0.0'. Also add apis as an array with the string './index.js'.

Express

const express = require('express');
const app = express();

app.get('/hello', (req, res) => {
  res.send('Hello World');
});

// Add swaggerOptions object here
// Your code here

Hint

Define swaggerOptions with definition and apis keys as described.

3

Generate swagger specification using swagger-jsdoc

Import swaggerJSDoc from 'swagger-jsdoc'. Then create a constant called swaggerSpec by calling swaggerJSDoc(swaggerOptions).

Express

const express = require('express');
const app = express();

app.get('/hello', (req, res) => {
  res.send('Hello World');
});

const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0'
    }
  },
  apis: ['./index.js']
};

// Import swaggerJSDoc and create swaggerSpec
// Your code here

Hint

Use require('swagger-jsdoc') to import and call it with swaggerOptions.

4

Serve the swagger JSON at a route

Add a GET route at /api-docs.json that sends the swaggerSpec JSON as the response. Then add app.listen(3000) to start the server on port 3000.

Express

const express = require('express');
const swaggerJSDoc = require('swagger-jsdoc');
const app = express();

app.get('/hello', (req, res) => {
  res.send('Hello World');
});

const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0'
    }
  },
  apis: ['./index.js']
};

const swaggerSpec = swaggerJSDoc(swaggerOptions);

// Add route to serve swaggerSpec and start server
// Your code here

Hint

Use app.get to serve swaggerSpec as JSON and app.listen(3000) to start the server.

Practice

1. What is the main purpose of swagger-jsdoc in an Express app?

easy

A. To connect to a database

B. To handle HTTP requests and responses

C. To generate API documentation from comments in your code

D. To serve static files like images and CSS

Solution

1. Step 1: Understand swagger-jsdoc role

   swagger-jsdoc reads specially formatted comments in your Express code to create API documentation automatically.

2. Step 2: Compare with other options

   Handling HTTP requests is Express's job, not swagger-jsdoc. Database connection and serving static files are unrelated tasks.

3. Final Answer:

   To generate API documentation from comments in your code -> Option C

4. Quick Check:

   swagger-jsdoc = API docs generator [OK]

Hint: swagger-jsdoc creates docs from code comments [OK]

Common Mistakes:

• Confusing swagger-jsdoc with Express routing
• Thinking swagger-jsdoc manages databases
• Assuming swagger-jsdoc serves static files

2. Which of the following is the correct way to import and initialize swagger-jsdoc in an ES modules-based Express app?

easy

A. import swaggerJSDoc from 'swagger-jsdoc'; const specs = swaggerJSDoc(options);

B. const swaggerJSDoc = require('swagger-jsdoc'); const specs = swaggerJSDoc();

C. const swaggerJSDoc = require('swagger-jsdoc'); const specs = swaggerJSDoc(options);

D. import swaggerJSDoc from 'swagger-jsdoc'; const specs = swaggerJSDoc();

Solution

1. Step 1: Use modern ES module import

   In modern Express apps using ES modules, import swaggerJSDoc from 'swagger-jsdoc' is correct.

2. Step 2: Initialize swagger-jsdoc with options

   swaggerJSDoc requires an options object to generate specs, so calling it without arguments is incorrect.

3. Final Answer:

   import swaggerJSDoc from 'swagger-jsdoc'; const specs = swaggerJSDoc(options); -> Option A

4. Quick Check:

   Import + call with options = C [OK]

Hint: Use import and pass options to swaggerJSDoc() [OK]

Common Mistakes:

• Calling swaggerJSDoc() without options
• Using require instead of import in ES modules
• Not assigning the result to a variable

3. Given this swagger-jsdoc options object, what will specs contain after calling swaggerJSDoc(options)?

const options = {
  definition: {
    openapi: '3.0.0',
    info: { title: 'Test API', version: '1.0.0' }
  },
  apis: ['./routes/*.js']
};
const specs = swaggerJSDoc(options);

medium

A. A string containing raw JavaScript code from './routes/*.js'

B. An object with OpenAPI info and paths extracted from comments in './routes/*.js'

C. An error because 'apis' path is incorrect

D. An empty object because no API comments exist

Solution

1. Step 1: Understand swagger-jsdoc output

   swagger-jsdoc returns a JSON object with OpenAPI info and paths parsed from specified files.

2. Step 2: Check options correctness

   The options specify OpenAPI version and info, and a valid path pattern for API files, so it will parse comments there.

3. Final Answer:

   An object with OpenAPI info and paths extracted from comments in './routes/*.js' -> Option B

4. Quick Check:

   swaggerJSDoc(options) = OpenAPI JSON object [OK]

Hint: swaggerJSDoc returns parsed OpenAPI JSON from code comments [OK]

Common Mistakes:

• Expecting raw code instead of parsed JSON
• Assuming error without checking file existence
• Thinking output is empty without comments

4. Identify the error in this swagger-jsdoc setup snippet:

import swaggerJSDoc from 'swagger-jsdoc';
import swaggerUi from 'swagger-ui-express';
const options = {
  definition: {
    openapi: '3.0.0',
    info: { title: 'API', version: '1.0' }
  },
  apis: ['./api/*.js']
};
const specs = swaggerJSDoc();

app.use('/docs', swaggerUi.serve, swaggerUi.setup(specs));

medium

A. swaggerJSDoc is called without passing the options object

B. The 'apis' path should be './api/*.ts' instead of '.js'

C. swaggerUi.setup() should be called before swaggerUi.serve

D. Missing import for swaggerUi from 'swagger-ui-express'

Solution

1. Step 1: Check swaggerJSDoc call

   The code calls swaggerJSDoc() without arguments, but it requires the options object to generate specs.

2. Step 2: Verify other parts

   The 'apis' path is valid for JavaScript files. swaggerUi.setup() after serve is correct usage.

3. Final Answer:

   swaggerJSDoc is called without passing the options object -> Option A

4. Quick Check:

   Call swaggerJSDoc(options) not empty () [OK]

Hint: Always pass options to swaggerJSDoc() [OK]

Common Mistakes:

• Calling swaggerJSDoc() without options
• Confusing order of swaggerUi middleware
• Ignoring missing imports

5. You want to set up swagger-jsdoc in your Express app to document APIs ONLY in routes/users.js and routes/products.js (assuming there are other .js files in the routes directory that should not be documented). Which apis option correctly includes both files for swagger-jsdoc?

hard

A. ['./routes/users.js', './routes/products']

B. ['./routes/*.js']

C. ['./routes/users.js|./routes/products.js']

D. ['./routes/users.js', './routes/products.js']

Solution

1. Step 1: Understand 'apis' option format

   The 'apis' option is an array of file paths or glob patterns to scan for comments.

2. Step 2: Check each option

   ['./routes/users.js', './routes/products.js'] lists both files explicitly, which is correct. ['./routes/*.js'] uses a glob that includes both files but may include others. ['./routes/users.js|./routes/products.js'] uses an invalid string with '|'. ['./routes/users.js', './routes/products'] has a missing file extension for products.js.

3. Final Answer:

   ['./routes/users.js', './routes/products.js'] -> Option D

4. Quick Check:

   List each file path separately in array [OK]

Hint: List each file path separately in 'apis' array [OK]

Common Mistakes:

• Using invalid string with '|' instead of array items
• Omitting file extensions
• Using too broad glob patterns unintentionally