API documentation best practices in Express - Practice Problems & Coding Challenges

Challenge - 5 Problems

🧠 Conceptual

intermediate

What is the primary purpose of API documentation?

Why do developers create API documentation for Express applications?

A To automatically generate database schemas

B To increase the server response speed

C To reduce the size of the application code

D To explain how to use the API endpoints clearly to other developers

💡 Hint

Think about what helps developers understand how to interact with the API.

API documentation helps developers understand how to use the API endpoints, what inputs they expect, and what outputs they return.

❓ component_behavior

intermediate

What output does this Express route documentation produce?

Given this API documentation snippet, what is the expected HTTP response when a GET request is made to /users?

Express

app.get('/users', (req, res) => {
  /**
   * @api {get} /users Get all users
   * @apiSuccess {Object[]} users List of user objects
   */
  res.json([{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }]);
});

A 404 Not Found

B {"users":[]}

C [{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]

D 500 Internal Server Error

💡 Hint

Look at the res.json call inside the route handler.

The route sends a JSON array of user objects as the response.

📝 Syntax

advanced

Which option correctly documents a POST endpoint with request body in Express?

Choose the correct JSDoc-style comment to document a POST /login endpoint that expects a JSON body with username and password fields.

A

/**
 * @api {post} /login User login
 * @apiParam {String} username User's username
 * @apiParam {String} password User's password
 * @apiSuccess {String} token Authentication token
 */

B

/**
 * @api {post} /login User login
 * @apiBody {String} username User's username
 * @apiBody {String} password User's password
 * @apiSuccess {String} token Authentication token
 */

C

/**
 * @api {post} /login User login
 * @apiRequest {String} username User's username
 * @apiRequest {String} password User's password
 * @apiSuccess {String} token Authentication token
 */

D

/**
 * @api {post} /login User login
 * @apiInput {String} username User's username
 * @apiInput {String} password User's password
 * @apiSuccess {String} token Authentication token
 */

💡 Hint

Look for the standard tag used to describe parameters in the request body.

The @apiParam tag is the correct way to document parameters expected in the request body for this style of API documentation.

🔧 Debug

advanced

Why does this API documentation fail to show request body parameters?

Consider this Express route and its documentation. Why will the generated API docs not show the expected request body parameters?

Express

app.post('/register', (req, res) => {
  /**
   * @api {post} /register Register user
   * @apiParam {String} email User email
   * @apiParam {String} password User password
   */
  res.send('User registered');
});

A The JSDoc comment is inside the route handler function, so the documentation tool cannot detect it.

B The @apiParam tags are misspelled and should be @apiBodyParam.

C The route method should be GET to document parameters correctly.

D The response does not include JSON, so documentation tools ignore the parameters.

💡 Hint

Think about where documentation comments should be placed for tools to parse them.

Documentation comments must be placed immediately before the route definition, not inside the function body, for tools to detect them properly.

❓ lifecycle

expert

When should API documentation be updated during Express app development?

Choose the best practice for maintaining API documentation in an Express project.

A Update documentation only before major releases to save time

B Update documentation immediately after adding or changing any API endpoint behavior

C Update documentation once a year during maintenance windows

D Update documentation only if users report issues

💡 Hint

Think about what keeps documentation accurate and useful for developers.

Keeping documentation updated immediately after changes ensures it stays accurate and helps developers avoid confusion.

Practice

1. Which of the following is the most important reason to write clear API documentation in Express?

easy

A. To make your code run faster

B. To reduce the size of your project files

C. To help other developers understand how to use your API without confusion

D. To avoid writing tests for your API

Solution

1. Step 1: Understand the purpose of API documentation

   API documentation explains how to use the API, including routes, parameters, and responses.

2. Step 2: Identify the main benefit of clear documentation

   Clear docs help other developers use the API correctly without confusion or mistakes.

3. Final Answer:

   To help other developers understand how to use your API without confusion -> Option C

4. Quick Check:

   Clear docs = help others [OK]

Hint: Think about who reads your docs: other developers [OK]

Common Mistakes:

• Confusing documentation with code optimization
• Thinking docs reduce file size
• Assuming docs replace testing

2. Which syntax is the best way to add a comment describing an Express route for documentation?

easy

A. // This route returns all users

B.

C. # This route returns all users

D. /* This route returns all users */

Solution

1. Step 1: Identify the comment style used in JavaScript/Express

   Express uses JavaScript, which supports single-line comments with // and multi-line with /* */.

2. Step 2: Choose the correct comment syntax for a single line

   Single-line comments use //, so // This route returns all users is correct.

3. Final Answer:

   // This route returns all users -> Option A

4. Quick Check:

   JS single-line comment = // [OK]

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

Common Mistakes:

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

3. Given this Express route with JSDoc comments, what is the documented HTTP method and path?

/**
 * Get all products
 * @route GET /products
 * @returns {Array} List of products
 */
app.get('/products', (req, res) => { res.send([]); });

medium

A. GET /products

B. DELETE /products

C. GET /product

D. POST /products

Solution

1. Step 1: Read the JSDoc comment for the route

   The comment says @route GET /products, indicating the HTTP method and path.

2. Step 2: Match the comment with the Express route

   The code uses app.get('/products'), matching the GET method and /products path.

3. Final Answer:

   GET /products -> Option A

4. Quick Check:

   JSDoc @route matches app.get path [OK]

Hint: Look for @route tag in comments to find method and path [OK]

Common Mistakes:

• Confusing GET with POST or DELETE
• Ignoring the exact path string
• Assuming plural vs singular path names

4. You wrote this Express route but forgot to document the expected query parameter. What is the best fix?

app.get('/search', (req, res) => {
  const term = req.query.term;
  res.send(`Searching for ${term}`);
});

medium

A. Remove the query parameter from the code

B. Add a JSDoc comment describing the 'term' query parameter

C. Change the route to POST to avoid query parameters

D. Add a console.log statement inside the route

Solution

1. Step 1: Identify missing documentation

   The route uses req.query.term but no comment explains this parameter.

2. Step 2: Add clear documentation for the query parameter

   Use JSDoc to describe the 'term' parameter so users know what to send.

3. Final Answer:

   Add a JSDoc comment describing the 'term' query parameter -> Option B

4. Quick Check:

   Document all parameters for clarity [OK]

Hint: Document every input your API expects [OK]

Common Mistakes:

• Ignoring query parameters in docs
• Changing HTTP method unnecessarily
• Adding logs instead of docs

5. You want to keep your Express API documentation close to your code and automatically generate docs for users. Which approach is best?

hard

A. Write separate markdown files manually and update them after code changes

B. Only write comments in code without any generation tool

C. Create a PDF document describing the API and email it to users

D. Use JSDoc comments in your route files and a tool like swagger-jsdoc to generate docs

Solution

1. Step 1: Understand the goal of keeping docs close to code

   Keeping docs near code helps keep them updated and reduces errors.

2. Step 2: Identify tools that generate docs from code comments

   JSDoc comments combined with swagger-jsdoc can auto-generate API docs from code.

3. Step 3: Compare options

   Manual markdown or PDFs are separate and can get outdated; comments alone don't generate docs.

4. Final Answer:

   Use JSDoc comments in your route files and a tool like swagger-jsdoc to generate docs -> Option D

5. Quick Check:

   Auto-generate docs from code comments = best practice [OK]

Hint: Use tools that generate docs from code comments automatically [OK]

Common Mistakes:

• Writing docs separately and forgetting updates
• Not using any generation tool
• Relying on static PDFs