Swagger/OpenAPI specification in Express

Introduction

Swagger/OpenAPI helps you describe your API clearly so others can understand and use it easily.

You want to share your API details with other developers.

You need to generate API documentation automatically.

You want to test your API endpoints interactively.

You want to keep your API design consistent and clear.

You want tools to generate client code from your API description.

Syntax

Express

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

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);

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

The openapi field sets the OpenAPI version.

The apis array points to files where you write comments describing your API.

Examples

Basic setup with API info and source file for comments.

Express

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

Example of a comment in your route file describing a GET /users endpoint.

Express

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Get all users
 *     responses:
 *       200:
 *         description: List of users
 */

Sample Program

This Express app has one route /hello and uses Swagger to document it. You can visit /api-docs to see the interactive 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 with Swagger',
    },
  },
  apis: ['./index.js'],
};

const swaggerSpec = swaggerJsdoc(options);

/**
 * @swagger
 * /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(swaggerSpec));

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

Important Notes

Write your API details in comments using @swagger tags to keep docs updated automatically.

Use swagger-ui-express to serve a friendly web page showing your API docs.

Keep your API description clear and simple for easy understanding.

Summary

Swagger/OpenAPI helps describe your API clearly for others.

You add special comments in your code to define endpoints and responses.

Use tools like swagger-ui-express to show interactive API docs in your app.