A JavaScript library that reads JSDoc-annotated source files and generates an OpenAPI (Swagger) specification from them, built for Node.js API developers who want their API documentation to live next to the route handlers it describes.

What it is

swagger-jsdoc is a Node.js library that parses @openapi and @swagger annotations embedded inside JSDoc comment blocks and assembles them into a single specification document. It lives in the JavaScript ecosystem and targets the OpenAPI 3.x, Swagger 2, and AsyncAPI 2.0 specification formats. Configuration is passed as a plain JavaScript object containing a definition block with the base specification (openapi, info, and related fields) and an apis array of glob patterns pointing at the source files that hold annotations.

The specific thing it replaces is hand-maintained specification files. Instead of keeping a separate YAML or JSON document in sync with the code by hand, the developer writes the route documentation directly above the handler that implements it, and the library collects those fragments at build or runtime. The returned object is a swagger tools-compatible and validated specification, ready to be handed to a UI renderer or a validator.

Key capabilities

• Parses @openapi and @swagger JSDoc blocks and merges them with a definition object supplied in options.
• Accepts an apis array of file globs, such as ./src/routes*.js, to select which annotated files are scanned.
• Emits a specification compatible with swagger tools and validated against the declared format.
• Supports OpenAPI 3.x, Swagger 2, and AsyncAPI 2.0 as output targets.
• Exposes a failOnErrors option that throws on parse or validation failure instead of proceeding, so documentation validity can be asserted inside a unit test.
• Ships as a CommonJS module in the v6 line, installable as the swagger-jsdoc npm package.

Who uses it and how

• Node.js API teams that want route documentation authored in the same file as the route handler, avoiding a second document to maintain.
• Projects with many route files, where the apis glob gathers annotations from directories rather than a single file.
• Teams that run documentation validation in CI by setting failOnErrors: true and asserting generated output inside tests.
• Applications targeting more than one specification format, since the same annotation source can produce OpenAPI 3.x, Swagger 2, or AsyncAPI 2.0 output.

Getting started

Install with npm install swagger-jsdoc --save or yarn add swagger-jsdoc, then call the exported function with an options object. The library requires Node.js 20.x or higher.

How it compares

The facts for this entry do not list any paid products that swagger-jsdoc replaces, and they do not name a competing generator, so no licence, hosting, or cost comparison can be drawn from them. It stands alone in this registry as a JSDoc-driven specification generator.

When to use it — and when not to

A self-hoster needs a Node.js 20.x or higher runtime; no database, object storage, or SMTP service is mentioned as a dependency, because the library runs in-process and produces a specification object rather than hosting a served documentation site. Teams that want a separately authored specification file, or that do not annotate route handlers with JSDoc, should not pick it, since the entire input is the annotation blocks and the apis file set. The README excerpt is thin on configuration detail and defers version-specific guidance to external docs trees, and the repository carries 47 open issues, so a prospective user should read the documentation for the exact version in use rather than relying on the top-level README alone.

/**
 * @openapi
 * /:
 *   get:
 *     description: Welcome to swagger-jsdoc!
 *     responses:
 *       200:
 *         description: Returns a mysterious string.
 */
app.get('/', (req, res) => {
  res.send('Hello World!');
});

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

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Hello World',
      version: '1.0.0',
    },
  },
  apis: ['./src/routes*.js'], // files containing annotations as above
};

const openapiSpecification = swaggerJsdoc(options);

npm install swagger-jsdoc --save

yarn add swagger-jsdoc

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

const options = {
  failOnErrors: true, // Whether or not to throw when parsing errors. Defaults to false.
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Hello World',
      version: '1.0.0',
    },
  },
  apis: ['./src/routes*.js'],
};

const openapiSpecification = swaggerJsdoc(options);