Documenting endpoints in Express - Practice Problems & Coding Challenges

Challenge - 5 Problems

❓ component_behavior

intermediate

What is the output of this Express endpoint documentation?

Consider this Express route documented with Swagger comments. What will the generated Swagger UI show for the GET /users endpoint?

Express

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

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Retrieve a list of users
 *     responses:
 *       200:
 *         description: A list of users.
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 type: string
 */
app.get('/users', (req, res) => {
  res.json(['Alice', 'Bob']);
});

A The Swagger UI shows a GET /users endpoint with a 200 response returning an array of strings.

B The Swagger UI shows a POST /users endpoint with no response documented.

C The Swagger UI shows a GET /users endpoint but no response schema is shown.

D The Swagger UI shows a GET /users endpoint with a 404 response documented.

💡 Hint

Look at the @swagger comment block and the HTTP method used.

The Swagger comment documents a GET /users endpoint with a 200 response returning an array of strings. This matches option A.

📝 Syntax

intermediate

Which option correctly documents a POST /login endpoint with a JSON body?

You want to document a POST /login endpoint that accepts a JSON body with username and password fields. Which Swagger comment block is correct?

A

/**
 * @swagger
 * /login:
 *   post:
 *     requestBody:
 *       content:
 *         application/xml:
 *           schema:
 *             type: object
 *             properties:
 *               username:
 *                 type: string
 *               password:
 *                 type: string
 *     responses:
 *       200:
 *         description: Login successful
 */

B

/**
 * @swagger
 * /login:
 *   get:
 *     parameters:
 *       - in: body
 *         name: user
 *         schema:
 *           type: object
 *           properties:
 *             username:
 *               type: string
 *             password:
 *               type: string
 *     responses:
 *       200:
 *         description: Login successful
 */

C

/**
 * @swagger
 * /login:
 *   post:
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               username:
 *                 type: string
 *               password:
 *                 type: string
 *     responses:
 *       200:
 *         description: Login successful
 */

D

/**
 * @swagger
 * /login:
 *   post:
 *     parameters:
 *       - in: query
 *         name: username
 *         schema:
 *           type: string
 *       - in: query
 *         name: password
 *         schema:
 *           type: string
 *     responses:
 *       200:
 *         description: Login successful
 */

💡 Hint

POST endpoints with JSON bodies use requestBody with application/json content type.

Option C correctly uses requestBody with application/json and defines username and password as string properties. Other options use wrong HTTP methods, wrong parameter locations, or wrong content types.

🔧 Debug

advanced

Why does this Swagger documentation not show the response schema?

This Express endpoint has Swagger comments but the response schema does not appear in the generated docs. What is the issue?

Express

/**
 * @swagger
 * /items:
 *   get:
 *     summary: Get items
 *     responses:
 *       200:
 *         description: List of items
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 type: object
 *                 properties:
 *                   id:
 *                     type: integer
 *                   name:
 *                     type: string
 */
app.get('/items', (req, res) => {
  res.json([{ id: 1, name: 'Item1' }]);
});

A The Swagger comment block is correct; the issue is likely in the Swagger UI configuration, not the code.

B The indentation of the Swagger comment is incorrect, so the parser ignores the schema.

C The Swagger parser requires the 'type' field to be 'object' at the root, so array is invalid here.

D The response schema is missing a required 'example' field, so it does not show.

💡 Hint

Check if the Swagger comment syntax matches the standard and if the UI setup might affect display.

The Swagger comment block is correctly formatted with proper indentation and schema. The array type is valid. Missing example fields do not prevent display. The issue is likely in the Swagger UI setup or loading.

❓ state_output

advanced

What is the documented response status code for this Express endpoint?

Given this Swagger comment for an Express endpoint, what status code is documented for the response?

Express

/**
 * @swagger
 * /profile:
 *   put:
 *     summary: Update user profile
 *     responses:
 *       204:
 *         description: Profile updated successfully
 *       400:
 *         description: Invalid input
 */
app.put('/profile', (req, res) => {
  if (!req.body.name) {
    return res.status(400).send('Name required');
  }
  res.status(204).send();
});

A 200

B 204

C 400

D 404

💡 Hint

Look at the responses section in the Swagger comment.

The documented successful response status code is 204, which means no content but success. 400 is for invalid input but not the main success code.

🧠 Conceptual

expert

Which statement about documenting Express endpoints with Swagger is true?

Select the one true statement about documenting Express endpoints using Swagger comments.

A Swagger comments must be placed inside the route handler function to be recognized.

B Swagger automatically generates endpoint documentation without any comments if Express routes exist.

C Response schemas in Swagger comments are optional and do not affect the generated documentation.

D The HTTP method in Swagger comments must match the Express route method exactly for correct documentation.

💡 Hint

Think about how Swagger matches comments to routes.

Swagger uses the HTTP method in comments to match the Express route method. They must match exactly (e.g., get, post). Comments outside route handlers are fine. Swagger does not auto-generate docs without comments. Response schemas improve docs but are optional.

Practice

1. Why is it important to document endpoints in an Express app?

easy

A. To help others understand what each route does and how to use it

B. To make the app run faster

C. To reduce the size of the code

D. To hide the routes from users

Solution

1. Step 1: Understand the purpose of documentation

   Documentation explains the purpose and usage of code parts, making it easier for others to understand.

2. Step 2: Relate documentation to endpoints

   Documenting endpoints clarifies what each route does and what data it expects, helping teammates and future you.

3. Final Answer:

   To help others understand what each route does and how to use it -> Option A

4. Quick Check:

   Documentation improves understanding = B [OK]

Hint: Documentation explains purpose and usage clearly [OK]

Common Mistakes:

• Thinking documentation improves speed
• Confusing documentation with code optimization
• Assuming documentation hides code

2. Which of the following is the correct way to add a comment documenting an Express route?

easy

A. # This route handles user login

B. // This route handles user login

C.

D. /* This route handles user login */

Solution

1. Step 1: Identify comment syntax in JavaScript

   JavaScript uses // for single-line comments and /* */ for multi-line comments.

2. Step 2: Match comment style to Express (Node.js) code

   Express routes are written in JavaScript, so // is correct for single-line comments.

3. Final Answer:

   // This route handles user login -> Option B

4. Quick Check:

   JavaScript single-line comment = // [OK]

Hint: Use // for single-line comments in Express (JavaScript) [OK]

Common Mistakes:

• Using HTML comments in JS code
• Using # which is for Python or shell scripts
• Confusing multi-line comment style for single-line

3. Given this Express route with documentation:

  // Returns user info by ID
  app.get('/user/:id', (req, res) => {
    const id = req.params.id;
    res.send(`User ID is ${id}`);
  });

What will the server respond with when a client requests /user/42?

medium

A. Error: Route not found

B. User ID is :id

C. User ID is 42

D. User ID is undefined

Solution

1. Step 1: Understand route parameter usage

   The route uses :id as a parameter, which is accessed via req.params.id.

2. Step 2: Substitute parameter value from URL

   When requesting /user/42, req.params.id is '42', so the response is 'User ID is 42'.

3. Final Answer:

   User ID is 42 -> Option C

4. Quick Check:

   Route param :id = 42 in response [OK]

Hint: Route params accessed via req.params.name [OK]

Common Mistakes:

• Using literal ':id' instead of param value
• Accessing req.body instead of req.params
• Expecting undefined if param missing

4. This Express route has a documentation comment:

  // Get all products
  app.get('/products', (req, res) => {
    res.send(productsList);
  });

But when running, it throws an error: ReferenceError: productsList is not defined. What is the likely fix?

medium

A. Define the variable productsList before using it in the route

B. Change app.get to app.post

C. Remove the comment to fix the error

D. Rename the route path to /product-list

Solution

1. Step 1: Analyze the error message

   The error says productsList is not defined, meaning the variable is missing or not declared.

2. Step 2: Fix by declaring the variable

   To fix, declare and assign productsList before the route uses it, so the route can send it properly.

3. Final Answer:

   Define the variable productsList before using it in the route -> Option A

4. Quick Check:

   ReferenceError means missing variable = define it [OK]

Hint: Check error message for missing variables [OK]

Common Mistakes:

• Changing HTTP method without reason
• Thinking comments cause runtime errors
• Changing route path unrelated to variable error

5. You want to document an Express POST endpoint that creates a new user. Which of these comments best explains the endpoint clearly and helps future developers?

hard

A. // POST endpoint

B. // This is a route

C. // Handle user data

D. // POST /users - Creates a new user. Expects JSON body with 'name' and 'email'. Returns the created user object.

Solution

1. Step 1: Identify clear and complete documentation

   The best comment explains the HTTP method, route path, expected input, and output clearly.

2. Step 2: Compare options for clarity

   // POST /users - Creates a new user. Expects JSON body with 'name' and 'email'. Returns the created user object. describes method (POST), path (/users), expected data (JSON with 'name' and 'email'), and response (created user object), making it most helpful.

3. Final Answer:

   // POST /users - Creates a new user. Expects JSON body with 'name' and 'email'. Returns the created user object. -> Option D

4. Quick Check:

   Complete, clear docs = // POST /users - Creates a new user. Expects JSON body with 'name' and 'email'. Returns the created user object. [OK]

Hint: Include method, path, input, and output in comments [OK]

Common Mistakes:

• Writing vague or incomplete comments
• Not mentioning expected data format
• Ignoring response details