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

Document your code and keep a live and reusable OpenAPI (Swagger) specification. This specification can be the core of your API-driven project: generate documentation, servers, clients, tests and much more based on the rich OpenAPI ecosystem of tools.

Goals

swagger-jsdoc enables you to integrate Swagger using JSDoc comments in your code. Just add @swagger (or @openapi) on top of your DocBlock and declare the meaning of your code in YAML complying to the OpenAPI specification. If you prefer to keep some parts of your specification aside your code in order to keep it lighter/cleaner, you can also pass these parts as separate input YAML files.

swagger-jsdoc will parse the above-mentioned and output an OpenAPI specification. You can use it to integrate any server and client technology as long as both sides comply with the specification.

Thus, the swagger-jsdoc project assumes that you want document your existing/living/working code in a way to "give life" to it, generating a specification which can then be fed into other Swagger tools, and not the vice-versa.

If you prefer to write the OpenAPI specification first and separately, you might check other projects facilitating this, such as

• swagger-editor
• swagger-node

Webpack integration

You can use this package with a webpack plugin to keep your swagger documentation up-to-date when building your app:

• 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.

Supported versions

• OpenAPI 3.x
• Swagger 2.0

To make sure your end specification is valid, do read the most up-to date official OpenAPI specification.

Installation

$ npm install swagger-jsdoc --save

Or using yarn

$ yarn add swagger-jsdoc

Fundamental concepts

Before you start writing your specification and/or documentation, please keep in mind that there are two fundamental concepts you need to wrap you head around when working with swagger-jsdoc - definition object and input APIs.

Definition object maps to OpenAPI object. This is where you would add information about your API and any root-level properties. Definition object is a required parameter.

Input APIs are any files which you pass as arguments to the program in order to extract information about your API. For instance, these could be .js files with JSDoc comments or .yaml files directly. This parameter is also required.

There are a few ways by which you can pass these 2 required arguments:

When using the CLI:

• Through apis property in your definition object.
• Through arguments

When using the Node API:

• Through apis in your options object.

For example, given the following module export for a definition object:

// Taken from example/v2/swaggerDef.js

module.exports = {
  info: {
    // API informations (required)
    title: 'Hello World', // Title (required)
    version: '1.0.0', // Version (required)
    description: 'A sample API', // Description (optional)
  },
  host, // Host (optional)
  basePath: '/', // Base path (optional)
};

One way you can make use of this definition is by using the CLI as following:

$ swagger-jsdoc -d example/v2/swaggerDef.js example/v2/route*.js

If you, however, want to skip the arguments and still use the CLI, you will need to update the definition object as following:

// Taken from example/v2/swaggerDef.js

module.exports = {
  ...
  apis: ['example/v2/route*.js'] // <-- We add this property:
  basePath: '/', // Base path (optional)
};

And then you will be able to use the CLI as following:

$ swagger-jsdoc -d example/v2/swaggerDef.js

When using the Node API, input APIs come in in the following way:

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

const swaggerDefinition = {
  ...
  basePath: '/', // Base path (optional)
};

const options = {
  swaggerDefinition,
  apis: ['./example/v2/routes*.js'], // <-- not in the definition, but in the options
};

const swaggerSpec = swaggerJSDoc(options);

Quick Start

Get started by documenting your code.

Note that swagger-jsdoc uses node glob module in the background when taking your files. This means that you can use patterns such as *.js to select all javascript files or **/*.js to select all javascript files in sub-folders recursively.

Paths provided are relative to the current directory from which you execute the program.

Examples

There are plenty of examples you can use to start off:

• example: contains an example app with version 2 of the specification. It will give you an idea how to annotate your comments in order to include them in the output specification.
• test/cli: CLI tests you can read to get ideas about the available functionalities of the CLI. (apart from the obvious help menu)
• test/example: various assets for tests you can also re-use for starting definitions, routes, etc.

CLI

On top of the Node API, there is also a command line interface.

Reporting issues

Before submitting new issues, please make sure you first search for existing such. It is quite possible that the topic you would like to bring up has been discussed already.

In case of an issue which hasn't been considered yet, please include as much information as possible about the issue. This will help maintainers and other users relate to your problem at hand.

For instance:

• Describe what you were doing when the issue appeared.
• Add a set of steps to reproduce your issue.
• Include screenshots.
• Give examples on expected vs actual behavior.

Contributing

• Fork the project and clone it locally.
• Create branches for each separate topic. Any standard you are used to follow for semantic commit messages will be highly appreciated.
• Comment your code as if you are going to maintain it in the future.
• Use the rich set of unit tests as an example and add your unit tests as well. This will not only enable you to programatically reproduce your fix faster than setting up an application, but it will also make you super cool! :)
• Push to your changes to the origin of your repository and create a new pull request towards the upstream master.

Thank you!