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.