Skip to content

Latest commit

 

History

History
117 lines (93 loc) · 4.14 KB

FIRST-STEPS.md

File metadata and controls

117 lines (93 loc) · 4.14 KB

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:

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

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:

Related projects