API documentation best practices in Express - Mini Project: Build & Apply

API Documentation Best Practices with Express

📖 Scenario: You are building a simple Express API for a bookstore. You want to document your API routes clearly so other developers can understand and use your API easily.

🎯 Goal: Create an Express API with clear documentation comments for each route using best practices. This will help other developers know what each route does, what parameters it expects, and what responses it returns.

📋 What You'll Learn

Create an Express app with a route to get all books

Add a configuration variable for the API version

Use JSDoc-style comments to document the route with method, path, parameters, and response

Add a final route to get API info including the version

💡 Why This Matters

🌍 Real World

Clear API documentation helps teams and external developers understand how to use your API without confusion or guesswork.

💼 Career

Writing good API docs is a key skill for backend developers, API designers, and anyone working with web services.

1

Set up Express app and initial route

Create an Express app by importing express and calling express(). Then create a route GET /books that sends a JSON array with two books: { id: 1, title: '1984' } and { id: 2, title: 'Brave New World' }.

Express

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

// Your code here

Need a hint?

Use require('express') to import Express and express() to create the app. Use app.get('/books', (req, res) => { ... }) to create the route.

2

Add API version configuration

Create a constant variable called apiVersion and set it to the string '1.0'.

Express

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

app.get('/books', (req, res) => {
  res.json([
    { id: 1, title: '1984' },
    { id: 2, title: 'Brave New World' }
  ]);
});

// Your code here

Need a hint?

Use const apiVersion = '1.0' to store the API version.

3

Add JSDoc-style documentation to the /books route

Add a JSDoc comment above the app.get('/books') route. Document the HTTP method as GET, the path as /books, describe that it returns a list of books, and specify that the response is a JSON array of objects with id and title fields.

Express

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

const apiVersion = '1.0';

/**
 * Your JSDoc comment here
 */
app.get('/books', (req, res) => {
  res.json([
    { id: 1, title: '1984' },
    { id: 2, title: 'Brave New World' }
  ]);
});

Need a hint?

Use /** ... */ to add a JSDoc comment. Include GET /books, a short description, and an @returns tag describing the JSON response.

4

Add a route to get API info including version

Add a new route GET /info that returns a JSON object with a version field set to the apiVersion variable. Also add a JSDoc comment documenting this route with method, path, and response.

Express

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

const apiVersion = '1.0';

/**
 * GET /books
 * Returns a list of books.
 * @returns {Array} JSON array of book objects
 */
app.get('/books', (req, res) => {
  res.json([
    { id: 1, title: '1984' },
    { id: 2, title: 'Brave New World' }
  ]);
});

// Your code here

Need a hint?

Create a new route app.get('/info', ...) that sends { version: apiVersion } as JSON. Add a JSDoc comment describing the route and response.