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.