Swagger/OpenAPI specification in Express - Practice Problems & Coding Challenges

Challenge - 5 Problems

❓ component_behavior

intermediate

What is the output of this Swagger UI setup code?

Consider this Express code snippet that sets up Swagger UI for API documentation. What will the user see when they visit /api-docs in their browser?

Express

import express from 'express';
import swaggerUi from 'swagger-ui-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.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

app.listen(3000);

A A web page showing interactive API documentation with endpoints from './routes/*.js' files.

B A JSON file download of the OpenAPI specification.

C A blank page because no routes are defined in the Express app.

D An error message because swaggerJsdoc is missing required fields.

💡 Hint

Think about what swaggerUi.serve and swaggerUi.setup do with the swaggerSpec object.

The swaggerJsdoc generates the OpenAPI spec from the specified files. swaggerUi.serve and swaggerUi.setup serve an interactive web page at '/api-docs' showing the API docs.

📝 Syntax

intermediate

Which option correctly defines a basic OpenAPI info object in swagger-jsdoc?

You want to define the API title and version in swagger-jsdoc options. Which snippet is syntactically correct?

A "info: { 'title': 'API', 'version': 1.0.0 }"

B "info: { title: 'API', version: 1.0 }"

C "info: { title: 'API', version: '1.0.0' }"

D "info: { title: API, version: '1.0.0' }"

💡 Hint

Check the quotes around strings and the version format.

The title and version must be strings. Option C correctly uses strings for both keys and values. Option C has version as a number without quotes, which is invalid. Option C uses a number 1.0 instead of string '1.0.0'. Option C misses quotes around API string.

🔧 Debug

advanced

Why does this Swagger UI setup show an empty page?

This Express app uses swagger-ui-express and swagger-jsdoc but the Swagger UI page is empty. What is the likely cause?

Express

import express from 'express';
import swaggerUi from 'swagger-ui-express';
import swaggerJsdoc from 'swagger-jsdoc';

const app = express();

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

const swaggerSpec = swaggerJsdoc(options);

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

app.listen(3000);

A The 'apis' path './nonexistent/*.js' does not match any files, so no endpoints are documented.

B The swaggerUi.setup function requires a second argument with custom CSS to display content.

C The swaggerJsdoc options object is missing the 'servers' property.

D The Express app is missing a route handler for '/docs'.

💡 Hint

Check if the 'apis' pattern points to existing files with JSDoc comments.

swagger-jsdoc reads JSDoc comments from files matching the 'apis' pattern. If no files match, the generated spec has no paths, so Swagger UI shows an empty page.

❓ state_output

advanced

What is the value of 'swaggerSpec.info.title' after running this code?

Given this swagger-jsdoc options object, what is the value of the title property in the generated swaggerSpec.info?

Express

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '2.0.0',
      description: 'API description here'
    }
  },
  apis: []
};

const swaggerSpec = swaggerJsdoc(options);

// What is swaggerSpec.info.title?

A '2.0.0'

B 'API description here'

C undefined

D 'My API'

💡 Hint

Look inside the 'definition' object under 'info'.

The 'title' property is set to 'My API' inside the 'info' object. swaggerJsdoc copies this into swaggerSpec.info.title.

🧠 Conceptual

expert

Which option best describes the role of 'swagger-jsdoc' in an Express app?

In an Express app using Swagger/OpenAPI, what is the main purpose of the 'swagger-jsdoc' package?

A It serves the Swagger UI web interface to display API documentation.

B It generates an OpenAPI specification object by parsing JSDoc comments in source files.

C It validates incoming API requests against the OpenAPI schema.

D It automatically generates Express route handlers from the OpenAPI spec.

💡 Hint

Think about what swagger-jsdoc does with your code comments.

swagger-jsdoc reads specially formatted JSDoc comments in your source files and produces a JSON OpenAPI spec object. It does not serve UI or validate requests.

Practice

1. What is the main purpose of using Swagger/OpenAPI specification in an Express app?

easy

A. To speed up the server response time

B. To clearly describe and document the API endpoints and their behavior

C. To automatically fix bugs in the code

D. To encrypt the API data for security

Solution

1. Step 1: Understand Swagger/OpenAPI role

   Swagger/OpenAPI is used to describe APIs so others can understand how to use them.

2. Step 2: Identify main purpose in Express

   It helps document endpoints, request parameters, and responses clearly.

3. Final Answer:

   To clearly describe and document the API endpoints and their behavior -> Option B

4. Quick Check:

   Swagger documents APIs clearly [OK]

Hint: Swagger is for API documentation, not performance or security [OK]

Common Mistakes:

• Thinking Swagger speeds up the server
• Confusing Swagger with security tools
• Assuming Swagger fixes code bugs automatically

2. Which of the following is the correct way to set up swagger-ui-express middleware in an Express app?

easy

A. app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

B. app.get('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

C. app.listen('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

D. app.post('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

Solution

1. Step 1: Recall Express middleware usage

   Middleware is added with app.use() for routes serving static or UI content.

2. Step 2: Identify swagger-ui-express setup

   swaggerUi.serve and swaggerUi.setup() are passed as middleware to app.use() for '/api-docs'.

3. Final Answer:

   app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument)); -> Option A

4. Quick Check:

   Use app.use for middleware setup [OK]

Hint: Use app.use for middleware, not app.get or app.listen [OK]

Common Mistakes:

• Using app.get instead of app.use for middleware
• Trying to listen on a route path
• Using app.post for serving docs

3. Given this Swagger snippet in an Express app, what HTTP method and path does it describe?

{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create a new user",
        "responses": {
          "201": {"description": "User created"}
        }
      }
    }
  }
}

medium

A. POST request to /users

B. DELETE request to /users

C. PUT request to /users

D. GET request to /users

Solution

1. Step 1: Read the Swagger path and method

   The snippet shows a path '/users' with a 'post' method defined.

2. Step 2: Match HTTP method and path

   The method is POST, and the path is '/users', meaning it creates a new user.

3. Final Answer:

   POST request to /users -> Option A

4. Quick Check:

   Method 'post' means POST request [OK]

Hint: Look for HTTP method keys like 'get', 'post' in paths [OK]

Common Mistakes:

• Confusing 'post' with 'get'
• Ignoring the path and focusing on responses
• Assuming default method is GET

4. You wrote this Swagger setup in your Express app but the docs page shows a blank screen:

import swaggerUi from 'swagger-ui-express';
import swaggerDocument from './swagger.json';

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

What is the likely error?

medium

A. swagger.json file path is incorrect

B. Wrong import syntax for swagger-ui-express

C. Using app.use instead of app.get for docs route

D. Missing swaggerDocument argument in swaggerUi.setup()

Solution

1. Step 1: Check swaggerUi.setup() usage

   swaggerUi.setup() requires the Swagger document as an argument to display docs.

2. Step 2: Identify missing argument

   The code calls swaggerUi.setup() without passing swaggerDocument, so no docs load.

3. Final Answer:

   Missing swaggerDocument argument in swaggerUi.setup() -> Option D

4. Quick Check:

   Always pass Swagger JSON to swaggerUi.setup() [OK]

Hint: Always pass your Swagger JSON to swaggerUi.setup() [OK]

Common Mistakes:

• Forgetting to pass swaggerDocument to setup()
• Using app.get instead of app.use for middleware
• Incorrect import syntax causing silent failure

5. You want to add a new GET endpoint '/products' with a query parameter 'category' described in your Swagger file. Which snippet correctly defines this parameter in OpenAPI 3.0?

hard

A. "parameters": [{"name": "category", "in": "header", "required": false, "schema": {"type": "string"}}]

B. "parameters": [{"name": "category", "in": "path", "required": true, "schema": {"type": "string"}}]

C. "parameters": [{"name": "category", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Filter products by category"}]

D. "parameters": [{"name": "category", "in": "body", "required": true, "schema": {"type": "string"}}]

Solution

1. Step 1: Identify correct parameter location for query

   Query parameters use "in": "query" and are usually optional.

2. Step 2: Check parameter details

   "parameters": [{"name": "category", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Filter products by category"}] correctly sets name, in, required false, type string, and description.

3. Final Answer:

   "parameters": [{"name": "category", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Filter products by category"}] -> Option C

4. Quick Check:

   Query params use "in": "query" [OK]

Hint: Query params use "in": "query", path params use "in": "path" [OK]

Common Mistakes:

• Using "in": "path" for query parameters
• Setting required true for optional query params
• Using "in": "body" which is invalid in OpenAPI 3.0