Skip to main content
Version: 8.x

First Steps

Specification version​

swagger-jsdoc was created in 2015. The OpenAPI as a concept did not exist, and thus the naming of the package itself.

The default target specification is 2.0. This provides backwards compatibility for many APIs written in the last couple of years.

In order to create a specification compatibile with 3.0 or higher, i.e. the so called OpenAPI, set this information in the swaggerDefinition:

import swaggerJsdoc from 'swagger-jsdoc';

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

const openapiSpecification = await swaggerJsdoc(options);

Annotating source code​

Place @swagger or @openapi on top of YAML-formatted specification parts:

/**
 * @swagger
 *
 * /login:
 *   post:
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: username
 *         in: formData
 *         required: true
 *         type: string
 *       - name: password
 *         in: formData
 *         required: true
 *         type: string
 */
app.post('/login', (req, res) => {
  // Your implementation comes here ...
});

Using YAML​

It's possible to source parts of your specification through YAML files.

Imagine having a file x-amazon-apigateway-integrations.yaml with the following contents:

x-amazon-apigateway-integrations:
  default-integration: &default-integration
    type: object
    x-amazon-apigateway-integration:
      httpMethod: POST
      passthroughBehavior: when_no_match
      type: aws_proxy
      uri: 'arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789:function:helloworldlambda/invocations'

The following is an acceptable reference to information from x-amazon-apigateway-integrations.yaml when it's defined within the apis input array.

  /**
   * @swagger
   * /aws:
   *   get:
   *     description: contains a reference outside this file
   *     x-amazon-apigateway-integration: *default-integration
   */
  app.get('/aws', (req, res) => {
    // Your implementation comes here ...
  });
};

Further resources​

Additional materials to inspire you:

Suggestions for extending this helpful list are welcome! Submit your article

Examples​

Here's a list of example public open-source usages of the package: