# swagger-jsdoc

> Generates swagger doc based on JSDoc

Latest version **6.3.0** (published 2026-05-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install swagger-jsdoc
pnpm add swagger-jsdoc
yarn add swagger-jsdoc
bun add swagger-jsdoc
```

Provides the command `swagger-jsdoc`.

## Health

**Score 58/100 (C)** — status: active.

Positive: has types package; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 6.3.0 |
| Published | 2026-05-22 |
| First published | 2015-06-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/swagger-jsdoc) |
| Module format | CommonJS |
| Node | >=20.0.0 |
| Dependencies | 6 |
| Unpacked size | 693.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1789 |
| Author | https://github.com/Surnet/swagger-jsdoc/graphs/contributors |
| Maintainers | chdanielmueller, sibelius, kalin.chernev |
| Keywords | swagger, openapi, jsdoc |

## Links

- npm: https://www.npmjs.com/package/swagger-jsdoc
- Repository: https://github.com/Surnet/swagger-jsdoc
- Issues: https://github.com/Surnet/swagger-jsdoc/issues
- npm.io page: https://npm.io/package/swagger-jsdoc

## Dependencies (6)

- [glob](https://npm.io/package/glob.md) 11.1.0
- [yaml](https://npm.io/package/yaml.md) 2.0.0-1
- [doctrine](https://npm.io/package/doctrine.md) 3.0.0
- [commander](https://npm.io/package/commander.md) 6.2.0
- [lodash.mergewith](https://npm.io/package/lodash.mergewith.md) ^4.6.2
- [@apidevtools/swagger-parser](https://npm.io/package/@apidevtools/swagger-parser.md) ^12.1.0

## Recent versions

- 6.3.0 (latest) — 2026-05-22
- 6.2.8 — 2023-01-16
- 6.2.7 — 2022-12-19
- 6.2.6 — 2022-12-19
- 6.2.5 — 2022-08-08
- 6.2.4 — 2022-08-04
- 6.2.3 — 2022-08-03
- 6.2.2 — 2022-08-02
- 6.2.1 — 2022-04-18
- 6.2.0 — 2022-04-01
- 7.0.0-rc.6 — 2021-03-12
- 6.1.0 — 2021-03-11
- 7.0.0-rc.5 — 2021-03-07
- 6.0.9 — 2021-03-07
- 7.0.0-rc.4 — 2021-03-01
- … 79 more at https://npm.io/package/swagger-jsdoc/versions

## README

# swagger-jsdoc

This library reads your [JSDoc](https://jsdoc.app/)-annotated source code and generates an [OpenAPI (Swagger) specification](https://swagger.io/specification/).

[![npm Downloads](https://img.shields.io/npm/dm/swagger-jsdoc.svg)](https://www.npmjs.com/package/swagger-jsdoc)
![CI](https://github.com/Surnet/swagger-jsdoc/workflows/CI/badge.svg)

## Getting started

Imagine having API files like these:

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

The library will take the contents of `@openapi` (or `@swagger`) with the following configuration:

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

The resulting `openapiSpecification` will be a [swagger tools](https://swagger.io/tools/)-compatible (and validated) specification.

![swagger-jsdoc example screenshot](./docs/screenshot.png)

## System requirements

- Node.js 20.x or higher

You are viewing `swagger-jsdoc` v6 which is published in CommonJS module system.

## Installation

```bash
npm install swagger-jsdoc --save
```

Or

```bash
yarn add swagger-jsdoc
```

## Supported specifications

- OpenAPI 3.x
- Swagger 2
- AsyncAPI 2.0

## Validation of swagger docs

By default `swagger-jsdoc` tries to parse all docs to it's best capabilities. If you'd like to you can instruct an Error to be thrown instead if validation failed by setting the options flag `failOnErrors` to `true`. This is for instance useful if you want to verify that your swagger docs validate using a unit test.

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

## Documentation

Click on the version you are using for further details:

- [7.x](https://github.com/Surnet/swagger-jsdoc/tree/v7/docs)
- [6.x](https://github.com/Surnet/swagger-jsdoc/tree/v6/docs)
- [5.x](https://github.com/Surnet/swagger-jsdoc/tree/v5)

---
_Source: https://npm.io/package/swagger-jsdoc · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._