swagger-jsdoc setup in Express - Practice Problems & Coding Challenges

Challenge - 5 Problems

❓ component_behavior

intermediate

What does this swagger-jsdoc setup output?

Given this Express app setup with swagger-jsdoc, what will the /api-docs.json endpoint return?

Express

import express from 'express';
import swaggerJSDoc from 'swagger-jsdoc';

const app = express();

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

const swaggerSpec = swaggerJSDoc(options);

app.get('/api-docs.json', (req, res) => {
  res.json(swaggerSpec);
});

app.listen(3000);

A An HTML page showing API documentation

B A plain text string describing the API routes

C A JSON object with OpenAPI info and paths from './routes/*.js' files

D An error because './routes/*.js' files are missing

💡 Hint

swagger-jsdoc generates a JSON spec from options and comments in specified files.

The swaggerJSDoc function reads the options and extracts API documentation from the specified files. It returns a JSON object following the OpenAPI format. The endpoint /api-docs.json sends this JSON as response.

📝 Syntax

intermediate

Which option correctly initializes swagger-jsdoc?

Choose the correct way to initialize swagger-jsdoc with OpenAPI 3.0 and info title 'My API'.

A swaggerJSDoc({ openapi: '3.0.0', info: { title: 'My API' }, apis: ['./api.js'] })

B swaggerJSDoc({ openapi: '3.0.0', apis: ['./api.js'] })

C swaggerJSDoc({ info: { title: 'My API' }, apis: ['./api.js'] })

D swaggerJSDoc({ definition: { openapi: '3.0.0', info: { title: 'My API' } }, apis: ['./api.js'] })

💡 Hint

The OpenAPI info must be inside a 'definition' object.

The swagger-jsdoc options require a definition key containing the OpenAPI version and info. Options A, C, and D miss this structure or info.

🔧 Debug

advanced

Why does swagger-jsdoc return an empty paths object?

You set up swagger-jsdoc with correct options but the generated JSON has an empty 'paths' object. What is the most likely cause?

Express

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

A The files in './src/routes/*.js' do not contain any JSDoc comments with Swagger annotations

B The 'definition' object is missing the 'servers' property

C The 'apis' path is relative and must be absolute

D The swagger-jsdoc package version is incompatible with OpenAPI 3.0

💡 Hint

swagger-jsdoc extracts API paths from special comments inside the files.

swagger-jsdoc reads the files listed in 'apis' and looks for JSDoc comments with Swagger annotations to build the 'paths' object. If these comments are missing, 'paths' will be empty.

❓ state_output

advanced

What is the effect of calling swaggerJSDoc multiple times with different options?

If you call swaggerJSDoc twice with different 'apis' arrays and merge the results, what will happen?

Express

const spec1 = swaggerJSDoc({ definition: { openapi: '3.0.0', info: { title: 'API1' } }, apis: ['./routes1/*.js'] });
const spec2 = swaggerJSDoc({ definition: { openapi: '3.0.0', info: { title: 'API2' } }, apis: ['./routes2/*.js'] });
const merged = { ...spec1, paths: { ...spec1.paths, ...spec2.paths } };

A swaggerJSDoc caches results and returns the first spec always

B The merged object combines paths from both specs but info will be from spec1 only

C The merged object will throw an error because swaggerJSDoc outputs are not mergeable

D The merged object will only contain paths from spec2

💡 Hint

swaggerJSDoc returns a plain object; merging is manual.

swaggerJSDoc returns a JSON object. Calling it multiple times returns separate specs. Merging paths manually combines endpoints, but other fields like 'info' remain from the first spec unless merged explicitly.

🧠 Conceptual

expert

What is the role of the 'apis' option in swagger-jsdoc?

Why do you specify file paths in the 'apis' option when configuring swagger-jsdoc?

A To tell swagger-jsdoc where to find JSDoc comments with Swagger annotations to generate API documentation

B To specify where swagger-jsdoc should output the generated JSON file

C To list the API endpoints that swagger-jsdoc will automatically create routes for

D To define the order in which API routes are loaded in the Express app

💡 Hint

Think about how swagger-jsdoc knows what to document.

The 'apis' option is an array of file paths or glob patterns. swagger-jsdoc scans these files for JSDoc comments containing Swagger annotations to build the API documentation JSON.