swagger-jsdoc

Generates swagger doc based on JSDoc

weekly downloads1.1M

versionv6.2.8

licenseMIT

categorybackend

swaggeropenapijsdoc

Overview

swagger-jsdoc is a code-first documentation tool that scans your JavaScript source files for JSDoc comments and generates a validated OpenAPI (formerly Swagger) specification. Instead of maintaining separate YAML or JSON files, you annotate your route handlers directly with @openapi or @swagger tags, and the package compiles these into a complete spec object at runtime or build time.

The package addresses a common pain point in API development: documentation drift. When API docs live in separate files, they frequently fall out of sync with actual implementation. By colocating documentation with route definitions, swagger-jsdoc makes it easier to keep specs accurate during code reviews and refactoring. With over 1.1 million weekly downloads, it's become a standard tool in the Node.js ecosystem for Express, Koa, Fastify, and other framework users.

swagger-jsdoc outputs a JavaScript object conforming to OpenAPI 3.0 or Swagger 2.0 specifications, which can be served through swagger-ui-express for interactive documentation, used for contract testing, or exported as static files. The package validates your annotations against the OpenAPI schema, catching errors like missing required fields or incorrect data types before they reach production.

It's particularly popular among teams practicing continuous integration, as the failOnErrors option can break builds when documentation is invalid or incomplete. This enforces documentation quality as part of the development workflow rather than treating it as an afterthought.

Quick Start

typescript

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

const app = express();

const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'User API',
      version: '1.0.0',
      description: 'API for managing user resources'
    },
    servers: [{ url: 'http://localhost:3000' }]
  },
  apis: ['./routes/*.js']
};

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

/**
 * @openapi
 * /users/{id}:
 *   get:
 *     summary: Retrieve a user by ID
 *     parameters:
 *       - name: id
 *         in: path
 *         required: true
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: User object
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 id:
 *                   type: integer
 *                 name:
 *                   type: string
 *                 email:
 *                   type: string
 *       404:
 *         description: User not found
 */
app.get('/users/:id', (req, res) => {
  const user = { id: req.params.id, name: 'John Doe', email: 'john@example.com' };
  res.json(user);
});

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

Use Cases

Express REST API Documentation: Annotate Express route handlers with request/response schemas, parameters, and examples. Generate a complete OpenAPI spec and serve it via swagger-ui-express at /api-docs, giving frontend developers and API consumers interactive documentation that stays current with your implementation.

CI/CD Documentation Validation: Enable failOnErrors in your test suite to fail builds when JSDoc annotations are malformed or incomplete. This prevents merging code with undocumented endpoints or invalid parameter definitions, treating API documentation as a first-class deliverable.

Microservices Schema Sharing: Each microservice generates its own OpenAPI spec from JSDoc annotations. These specs can be aggregated into a service mesh documentation portal or used by API gateways for request validation and routing configuration.

Contract Testing Setup: Export the generated OpenAPI specification to JSON and use it with tools like Pact or Dredd for consumer-driven contract testing. The spec serves as the source of truth for both documentation and automated API validation.

Automated Client Generation: Feed the generated OpenAPI spec into tools like openapi-generator or swagger-codegen to create type-safe client libraries in TypeScript, Python, Java, or other languages, ensuring clients stay synchronized with server-side changes.

Pros & Cons

Pros

+Documentation colocated with code reduces drift and improves maintainability during refactoring
+Runtime spec generation means no separate YAML/JSON files to keep synchronized manually
+Built-in OpenAPI validation catches schema errors early with clear error messages
+Flexible configuration supports multiple API versions and file patterns via glob matching
+Works with any Node.js HTTP framework (Express, Koa, Fastify, Hapi) since it only parses files

Cons

−YAML-in-JSDoc comments can become verbose and harder to read than dedicated spec files for complex schemas
−No IDE autocomplete or syntax highlighting for YAML inside JSDoc blocks without plugins
−Runtime parsing adds startup overhead when scanning many files (mitigated by caching or build-time generation)
−Reusable components ($ref) require separate definition objects, not as elegant as pure YAML
−Error messages reference YAML line numbers within JSDoc strings, making debugging annotations tedious

Install

bash

npm install swagger-jsdoc

bash

pnpm add swagger-jsdoc

bash

bun add swagger-jsdoc

Overview

Quick Start

typescript

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

const app = express();

const swaggerOptions = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'User API',
      version: '1.0.0',
      description: 'API for managing user resources'
    },
    servers: [{ url: 'http://localhost:3000' }]
  },
  apis: ['./routes/*.js']
};

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

/**
 * @openapi
 * /users/{id}:
 *   get:
 *     summary: Retrieve a user by ID
 *     parameters:
 *       - name: id
 *         in: path
 *         required: true
 *         schema:
 *           type: integer
 *     responses:
 *       200:
 *         description: User object
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 id:
 *                   type: integer
 *                 name:
 *                   type: string
 *                 email:
 *                   type: string
 *       404:
 *         description: User not found
 */
app.get('/users/:id', (req, res) => {
  const user = { id: req.params.id, name: 'John Doe', email: 'john@example.com' };
  res.json(user);
});

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

Use Cases

Pros & Cons

Pros

+Documentation colocated with code reduces drift and improves maintainability during refactoring
+Runtime spec generation means no separate YAML/JSON files to keep synchronized manually
+Built-in OpenAPI validation catches schema errors early with clear error messages
+Flexible configuration supports multiple API versions and file patterns via glob matching
+Works with any Node.js HTTP framework (Express, Koa, Fastify, Hapi) since it only parses files

Cons

−YAML-in-JSDoc comments can become verbose and harder to read than dedicated spec files for complex schemas
−No IDE autocomplete or syntax highlighting for YAML inside JSDoc blocks without plugins
−Runtime parsing adds startup overhead when scanning many files (mitigated by caching or build-time generation)
−Reusable components ($ref) require separate definition objects, not as elegant as pure YAML
−Error messages reference YAML line numbers within JSDoc strings, making debugging annotations tedious