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

swagger-jsdoc enables to integrate Swagger using JSDoc.

Supported Swagger Versions

• 2.0

Install

$ npm install swagger-jsdoc --save

Quick Start

swagger-jsdoc returns the validated swagger specification as JSON.

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

var options = {
  swaggerDefinition: {
    info: {
      title: 'Hello World', // Title (required)
      version: '1.0.0', // Version (required)
    },
  },
  apis: ['./routes.js'], // Path to the API docs
};

// Initialize swagger-jsdoc -> returns validated swagger spec in json format
var swaggerSpec = swaggerJSDoc(options);

At this time you can do with the swaggerSpec whatever you want. The simplest way would be serving it straight to the outside world:

app.get('/api-docs.json', function(req, res) {
  res.setHeader('Content-Type', 'application/json');
  res.send(swaggerSpec);
});

You could also use a framework like swagger-tools to serve the spec and a swagger-ui.

How to document the API

The API can now be documented in JSDoc-style with swagger spec in YAML.

/**
 * @swagger
 * /login:
 *   post:
 *     description: Login to the application
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: username
 *         description: Username to use for login.
 *         in: formData
 *         required: true
 *         type: string
 *       - name: password
 *         description: User's password.
 *         in: formData
 *         required: true
 *         type: string
 *     responses:
 *       200:
 *         description: login
 */
app.post('/login', function(req, res) {
  res.json(req.body);
});

Re-using Model Definitions

A model may be the same for multiple endpoints (Ex. User POST,PUT responses). In place of writing (or copy and pasting) the same code into multiple locations, which can be error prone when adding a new field to the schema. You can define a model and re-use it across multiple endpoints. You can also reference another model and add fields.

/**
 * @swagger
 * definition:
 *   NewUser:
 *     type: object
 *     required:
 *       - username
 *       - password
 *     properties:
 *       username:
 *         type: string
 *       password:
 *         type: string
 *         format: password
 *   User:
 *     allOf:
 *       - $ref: '#/definitions/NewUser'
 *       - required:
 *         - id
 *       - properties:
 *         id:
 *           type: integer
 *           format: int64
 */

/**
   * @swagger
   * /users:
   *   get:
   *     description: Returns users
   *     produces:
   *      - application/json
   *     responses:
   *       200:
   *         description: users
   *         schema:
   *           type: array
   *           items: 
   *             $ref: '#/definitions/User'
   */
  app.get('/users', function(req, res) {
    res.json([ {
      id: 1,
      username: 'jsmith',
    }, {1
      id: 2,
      username: 'jdoe',
    } ]);
  });

  /**
   * @swagger
   * /users:
   *   post:
   *     description: Returns users
   *     produces:
   *       - application/json
   *     parameters:
   *       - name: user
   *         description: User object
   *         in:  body
   *         required: true
   *         type: string
   *         schema:
   *           $ref: '#/definitions/NewUser'
   *     responses:
   *       200:
   *         description: users
   *         schema:
   *           $ref: '#/definitions/User'
   */
  app.post('/users', function(req, res) {
    // Generate ID
    req.body.id = Math.floor(Math.random() * 100) * 1
    res.json(req.body);
  });

Example App

There is an example app in the example subdirectory. To use it you can use the following commands:

$ git clone https://github.com/Surnet/swagger-jsdoc.git
$ cd swagger-jsdoc
$ npm install
$ npm start

The swagger spec will be served at http://localhost:3000/api-docs.json

Changelog

v1.1.2 (2015/11/25 10:06 +00:00)

• fb86b3d Update version number to 1.1.2 (@chdanielmueller)
• #11 Merge pull request #11 from trendfischer/master (@trendfischer)
• b1695c0 Removed required path module (@trendfischer)
• ec1de9c Removed filename restriction for "*.js" (@trendfischer)