How to Document API in Express: Simple Guide with Examples

To document an API in Express, use tools like Swagger or JSDoc to describe your endpoints, request parameters, and responses. Integrate these tools by adding comments or JSON/YAML files and serve the documentation via a route in your Express app.

Syntax

API documentation in Express typically involves defining endpoint details using comments or configuration files. For example, Swagger uses a JSON or YAML format to describe routes, methods, parameters, and responses. You then serve this documentation using middleware like swagger-ui-express.

Key parts include:

• Paths: Define each API endpoint URL.
• Methods: HTTP methods like GET, POST, PUT, DELETE.
• Parameters: Query, path, or body inputs.
• Responses: Expected status codes and data formats.

javascript

const swaggerDocument = {
  openapi: '3.0.0',
  info: {
    title: 'API Documentation',
    version: '1.0.0'
  },
  paths: {
    '/users': {
      get: {
        summary: 'Get all users',
        responses: {
          '200': {
            description: 'A list of users'
          }
        }
      }
    }
  }
};

Example

This example shows how to document an Express API using Swagger UI. It sets up a simple GET endpoint and serves interactive API docs at /api-docs.

javascript

import express from 'express';
import swaggerUi from 'swagger-ui-express';

const app = express();

const swaggerDocument = {
  openapi: '3.0.0',
  info: {
    title: 'Simple API',
    version: '1.0.0'
  },
  paths: {
    '/hello': {
      get: {
        summary: 'Returns a greeting',
        responses: {
          '200': {
            description: 'Successful response',
            content: {
              'application/json': {
                schema: {
                  type: 'object',
                  properties: {
                    message: { type: 'string' }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
};

app.get('/hello', (req, res) => {
  res.json({ message: 'Hello, world!' });
});

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
  console.log('API docs at http://localhost:3000/api-docs');
});

Output

Server running on http://localhost:3000
API docs at http://localhost:3000/api-docs

Common Pitfalls

Common mistakes when documenting Express APIs include:

• Not keeping documentation updated with code changes, causing mismatches.
• Missing response schemas or unclear parameter descriptions.
• Serving documentation on a route without proper middleware setup.
• Using outdated Swagger/OpenAPI versions causing compatibility issues.

Always test your documentation UI and keep comments or JSON files in sync with your API.

javascript

/* Wrong: Missing response schema and no middleware to serve docs */
const swaggerDocWrong = {
  openapi: '3.0.0',
  info: { title: 'API', version: '1.0' },
  paths: {
    '/test': {
      get: {
        summary: 'Test endpoint'
        // Missing responses
      }
    }
  }
};

// Right: Add responses and use swagger-ui-express middleware
// See Example section for correct setup.

Quick Reference

Tips for documenting Express APIs:

• Use swagger-ui-express to serve Swagger docs easily.
• Write clear summaries and descriptions for each endpoint.
• Define request parameters and response schemas precisely.
• Keep your documentation updated with API changes.
• Test your docs by visiting the documentation route in a browser.

Key Takeaways

Use Swagger or JSDoc tools to create clear API documentation in Express.

Serve documentation with middleware like swagger-ui-express on a dedicated route.

Keep documentation updated and test it regularly to avoid mismatches.

Define all endpoints, parameters, and responses clearly in your docs.

Avoid missing response schemas and outdated documentation formats.