swagger-jsdoc setup in Express

Introduction

swagger-jsdoc helps you create clear API documentation automatically from your code comments. It makes your API easy to understand for others.

You want to document your Express API endpoints clearly.

You need a simple way to keep API docs updated with your code.

You want to generate Swagger UI docs for your API.

You want to share API details with frontend or other teams.

You want to test your API interactively using Swagger UI.

Syntax

Express

const swaggerJSDoc = require('swagger-jsdoc');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'API Title',
      version: '1.0.0',
      description: 'API description here',
    },
  },
  apis: ['./routes/*.js'],
};

const swaggerSpec = swaggerJSDoc(options);

definition holds the main API info and OpenAPI version.

apis is an array of file paths where swagger-jsdoc looks for comments.

Examples

Basic setup pointing to a single file app.js for API comments.

Express

const swaggerJSDoc = require('swagger-jsdoc');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0'
    },
  },
  apis: ['./app.js'],
};

const swaggerSpec = swaggerJSDoc(options);

Setup with multiple files listed for API documentation comments.

Express

const swaggerJSDoc = require('swagger-jsdoc');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'User API',
      version: '2.0.0',
      description: 'User management endpoints',
    },
  },
  apis: ['./routes/users.js', './routes/auth.js'],
};

const swaggerSpec = swaggerJSDoc(options);

Sample Program

This example sets up an Express server with swagger-jsdoc and swagger-ui-express. It documents a simple /hello GET endpoint that returns a greeting. The Swagger UI is available at /api-docs.

Express

const express = require('express');
const swaggerJSDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const app = express();

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

const swaggerSpec = swaggerJSDoc(options);

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

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

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

Important Notes

Make sure your API comment blocks use the correct @openapi or Swagger syntax for swagger-jsdoc to parse them.

Use swagger-ui-express to serve the generated docs in a friendly web page.

Keep the apis paths updated to include all files with API comments.

Summary

swagger-jsdoc generates API docs from comments in your code.

It needs a config object with API info and file paths.

Use swagger-ui-express to show docs in the browser.