swagger-jsdoc setup in Express - Cheat Sheet & Quick Revision

Recall & Review

beginner

What is swagger-jsdoc used for in an Express app?

swagger-jsdoc generates API documentation from JSDoc comments in your code. It helps create a Swagger (OpenAPI) specification automatically.

beginner

Which package do you use alongside swagger-jsdoc to serve the API docs in Express?

You use swagger-ui-express to serve the generated Swagger UI documentation in your Express app.

intermediate

What is the purpose of the swaggerDefinition object in swagger-jsdoc setup?

It defines the basic info about your API like title, version, description, and server URLs. This info appears in the generated docs.

intermediate

How do you tell swagger-jsdoc where to find your API route files for documentation?

You specify the file paths or glob patterns in the apis array option when configuring swagger-jsdoc.

intermediate

What is the typical Express middleware setup to serve Swagger UI using swagger-jsdoc?

You create the swaggerSpec with swagger-jsdoc, then use app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec)) to serve docs at /api-docs.

What does swagger-jsdoc generate from your code comments?

A OpenAPI specification JSON

B HTML pages for your website

C Database schemas

D CSS stylesheets

swagger-jsdoc reads JSDoc comments and creates an OpenAPI (Swagger) JSON spec describing your API.

Which Express middleware package is commonly used to display swagger-jsdoc output as a web page?

A express-session

B body-parser

C cors

D swagger-ui-express

swagger-ui-express serves the Swagger UI interface to visualize the API docs generated by swagger-jsdoc.

Where do you specify the API info like title and version in swagger-jsdoc?

A In the .env environment file

B In the Express app.listen() method

C In the swaggerDefinition object

D In the package.json file

The swaggerDefinition object holds metadata about your API, such as title, version, and description.

How do you tell swagger-jsdoc which files to scan for API documentation comments?

A By importing them in app.js

B By listing file paths in the apis array option

C By naming files swagger.js

D By placing files in a docs folder

You provide file paths or glob patterns in the apis array so swagger-jsdoc knows where to find JSDoc comments.

What URL path is commonly used to serve Swagger UI docs in an Express app?

A /api-docs

B /docs

C /swagger

D /documentation

The path /api-docs is a common convention to serve Swagger UI documentation in Express apps.

Explain the steps to set up swagger-jsdoc and swagger-ui-express in an Express app.

Think about installation, configuration, generating spec, and serving docs.

Describe how swagger-jsdoc uses JSDoc comments to create API documentation.

Focus on the role of comments and how swagger-jsdoc processes them.

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