swagger-jsdoc

What is swagger-jsdoc?

swagger-jsdoc is a Node.js library that allows you to integrate Swagger/OpenAPI documentation into your Express.js or other Node.js applications. It generates the Swagger specification based on JSDoc comments in your code, making it easier to maintain and update API documentation.

What are swagger-jsdoc's main functionalities?

Generate Swagger Documentation

This feature allows you to generate Swagger documentation from JSDoc comments in your code. The `options` object specifies the OpenAPI version, API info, and the files containing the JSDoc comments.

const swaggerJsdoc = require('swagger-jsdoc');
const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Express API with Swagger',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'], // files containing annotations as above
};
const swaggerSpec = swaggerJsdoc(options);

Integrate with Express

This feature demonstrates how to integrate Swagger UI with an Express application. The Swagger documentation is served at the `/api-docs` endpoint.

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

const app = express();
const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Express API with Swagger',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'],
};
const swaggerSpec = swaggerJsdoc(options);

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

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

JSDoc Annotations

This feature shows how to use JSDoc annotations to document an API endpoint. The annotations provide metadata about the endpoint, such as the HTTP method, summary, and response schema.

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Retrieve a list of users
 *     responses:
 *       200:
 *         description: A list of users
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 type: object
 *                 properties:
 *                   id:
 *                     type: integer
 *                   name:
 *                     type: string
 */
app.get('/users', (req, res) => {
  res.json([{ id: 1, name: 'John Doe' }]);
});

Other packages similar to swagger-jsdoc

swagger-ui-express

swagger-ui-express is a middleware for Express.js that serves auto-generated Swagger UI. It is often used in conjunction with swagger-jsdoc to serve the generated Swagger documentation. While swagger-jsdoc focuses on generating the Swagger specification, swagger-ui-express focuses on serving it in a user-friendly interface.

openapi-generator

openapi-generator is a tool that can generate client libraries, server stubs, API documentation, and configuration from an OpenAPI Specification. Unlike swagger-jsdoc, which generates the OpenAPI spec from JSDoc comments, openapi-generator takes an existing OpenAPI spec and generates code and documentation from it.

redoc

redoc is a tool for generating API documentation from OpenAPI specifications. It provides a customizable and responsive HTML documentation. Unlike swagger-jsdoc, which generates the OpenAPI spec, redoc focuses on rendering the documentation from an existing spec.

README

swagger-jsdoc

This library reads your JSDoc-annotated source code and generates an OpenAPI (Swagger) specification.

Getting started

swagger-jsdoc returns the validated OpenAPI specification as JSON or YAML.

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

const options = {
  swaggerDefinition: {
    openapi: '3.0.0',
    info: {
      title: 'Hello World',
      version: '1.0.0',
    },
  },
  apis: ['./src/routes*.js'],
};

const swaggerSpecification = swaggerJsdoc(options);

• options.definition is also acceptable. Pass an oasObject
• options.apis are resolved with node-glob. Construct these patterns carefully in order to reduce the number of possible matches speeding up files' discovery. Values are relative to the current working directory.

Use any of the swagger tools to get the benefits of your swaggerSpecification.

Node.js version requirements, CommonJS and ESM

swagger-jsdoc 6.x requires Node.js 12.x and above. When using the CLI, the library will attempt to load the definition file in several formats: .js, .cjs, .yaml (or .yml) and .json.

The example above follows the CommonJS format, which will work when you do not have "type": "module" in your package.json.

However, if you're using ESM and have "type": "module", then please change the extension to .cjs.

Definition files in .js and ESM will be supported in swagger-jsdoc 7.x.

Installation

npm install swagger-jsdoc --save

Or

yarn add swagger-jsdoc

Supported specifications

• OpenAPI 3.x
• Swagger 2

Documentation

Detailed documentation is available within /docs folder.

Webpack integrations

• swagger-jsdoc-webpack-plugin - Rebuild the swagger definition based on a predefined list of files on each webpack build.
• swagger-jsdoc-sync-webpack-plugin - Rebuild the swagger definition based on the files imported in your app on each webpack build.

Changelog

v6.0.5 (2021/02/15 15:52 +00:00)

• 05bc5a9 bump (@kalinchernev)
• a56522f changelog (@kalinchernev)
• #247 feat: support cjs and update docs (#247) (@kalinchernev)