API documentation best practices in Express - Interactive Code Practice

Practice - 5 Tasks

1fill in blank

easy

Complete the code to add a description to the API endpoint using Swagger comments.

Express

app.get('/users', /** [1] */ (req, res) => { res.send('User list'); });

Drag options to blanks, or click blank then click option'

A@desc

B@route

C@swagger

D@param

Attempts:

3 left

💡 Hint

Common Mistakes

Using @route instead of @desc for description

Using @param when no parameters are described

The @desc tag is used to add a description to the API endpoint in Swagger comments.

2fill in blank

medium

Complete the code to specify the HTTP method in Swagger documentation.

Express

/**
 * [1] GET /users
 * Returns list of users
 */
app.get('/users', (req, res) => { res.send('User list'); });

Drag options to blanks, or click blank then click option'

A@method

B@get

C@route

D@desc

Attempts:

3 left

💡 Hint

Common Mistakes

Using @method which is not a standard Swagger tag

Using @desc instead of @route

The @route tag specifies the HTTP method and path in Swagger documentation.

3fill in blank

hard

Fix the error in the Swagger comment to correctly document a query parameter.

Express

/**
 * @route GET /search
 * @desc Search users
 * @param [1] query.string.required - search term
 */
app.get('/search', (req, res) => { res.send('Search results'); });

Drag options to blanks, or click blank then click option'

AsearchTerm

Bterm

Cquery

Dq

Attempts:

3 left

💡 Hint

Common Mistakes

Using parameter names that don't match the query string

Using descriptive names instead of actual query keys

The query parameter name should match the actual query key used in the URL, commonly 'q' for search queries.

4fill in blank

hard

Fill both blanks to document a POST endpoint with a JSON body parameter.

Express

/**
 * @route POST /users
 * @desc Create a new user
 * @param [1] body.object.required - user data
 * @param [2] body.object.required.name - user's name
 */
app.post('/users', (req, res) => { res.send('User created'); });

Drag options to blanks, or click blank then click option'

Auser

BuserData

Cusername

Dname

Attempts:

3 left

💡 Hint

Common Mistakes

Using inconsistent names between the object and its properties

Using property names that don't match the data structure

The body parameter is named 'userData' to represent the user object, and the nested property is 'name' for the user's name.

5fill in blank

hard

Fill all three blanks to document a response with status code and description.

Express

/**
 * @route DELETE /users/[1]
 * @desc Delete a user by ID
 * [2] id path.string.required - user ID
 * [3] 204 - No content
 */
app.delete('/users/:id', (req, res) => { res.status(204).send(); });

Drag options to blanks, or click blank then click option'

Aid

BuserId

C@param

D@returns

Attempts:

3 left

💡 Hint

Common Mistakes

Using wrong parameter names that don't match the route

Mixing up @param and @returns tags

The path parameter is named 'id', the tag for path parameters is '@param', and the tag for responses is '@returns'.