How to Use Swagger with Express for API Documentation

To use swagger with express, install swagger-ui-express and swagger-jsdoc packages, define your API specs in a Swagger format, then serve the docs using swagger-ui-express middleware. This setup provides a web page where you can explore and test your API endpoints interactively.

Syntax

Here is the basic syntax to set up Swagger with Express:

• swagger-jsdoc: Generates Swagger specification from JSDoc comments or config.
• swagger-ui-express: Serves the Swagger UI web interface.
• app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs)): Mounts the Swagger UI at the /api-docs route.

javascript

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

const app = express();

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'API Docs',
      version: '1.0.0'
    }
  },
  apis: ['./routes/*.js'] // files containing annotations
};

const specs = swaggerJSDoc(options);

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

app.listen(3000);

Example

This example shows a simple Express server with Swagger UI serving API docs at /api-docs. It documents a single GET endpoint /hello.

javascript

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

const app = express();

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Simple API',
      version: '1.0.0',
      description: 'A simple Express API with Swagger'
    }
  },
  apis: ['./index.js']
};

const specs = swaggerJSDoc(options);

/**
 * @openapi
 * /hello:
 *   get:
 *     summary: Returns a greeting message
 *     responses:
 *       200:
 *         description: Greeting message
 *         content:
 *           text/plain:
 *             schema:
 *               type: string
 */
app.get('/hello', (req, res) => {
  res.send('Hello, world!');
});

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

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

Output

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

Common Pitfalls

• Not specifying the correct apis path in swagger-jsdoc options causes no docs to appear.
• Forgetting to use swaggerUi.serve middleware before swaggerUi.setup() breaks the UI.
• Incorrect or missing OpenAPI version in the definition leads to errors.
• Not restarting the server after changes to Swagger comments means docs won't update.

javascript

/* Wrong way: Missing swaggerUi.serve middleware */
app.use('/api-docs', swaggerUi.setup(specs));

/* Right way: Include swaggerUi.serve before setup */
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));

Quick Reference

Summary tips for using Swagger with Express:

• Install swagger-ui-express and swagger-jsdoc via npm.
• Define your API schema using OpenAPI 3.0 format.
• Use JSDoc comments to document endpoints inline.
• Mount Swagger UI middleware on a route like /api-docs.
• Access http://localhost:3000/api-docs to view interactive docs.

Key Takeaways

Install and use swagger-ui-express and swagger-jsdoc to integrate Swagger with Express.

Define your API documentation using OpenAPI 3.0 format and JSDoc comments.

Serve Swagger UI on a route like /api-docs to provide interactive API docs.

Always include swaggerUi.serve middleware before swaggerUi.setup for the UI to work.

Restart your server after updating Swagger comments to refresh the documentation.