Using Swagger

Swagger Setup

      
'use strict';

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

module.exports = server => {


    const options = {
        swaggerDefinition: {
            openapi: "3.0.0",
            info: {
                title: 'Todo API', // Title (required)
                version: '0.0.0', // Version (required)
            },
            servers:  [
              {
                url: 'https://my.example.com/api/v1',
                description: 'Live Server'
              },
              {
                url: '/api/v1',
                description: 'Local Server'
              }
            ],
            tags: [
              {
                name: "Tasks",
                description: "Things to do."
              }
            ]
        },
        apis: ['./models/**/*.model.js', './api/**/*.controller.js'],
    };

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

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

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

};
      
    

Controllers

      
'use strict';

const express = require('express');

module.exports = (app) => {

  app.services.logger.debug('Tasks Controller Loaded');

  const router = express.Router();

  /**
   *  @swagger
   *  /tasks:
   *    get:
   *      tags:
   *        - Tasks
   *      description: Get collection of all tasks
   *      produces:
   *      responses:
   *        200:
   *          content:
   *            application/json:
   *              description: tasks
   *              schema:
   *                type: array
   *                items:
   *                  $ref: '#/components/schemas/Task'
   */
  router.get('/', (req, res) => {

    app.models.tasks
      .find()
      .then(docs => res.json(docs))
      .catch(sendError(res));
  });

  /**
   *  @swagger
   *  /tasks:
   *    post:
   *      tags:
   *        - Tasks
   *      description: Add a task
   *      requestBody:
   *        required: true
   *        content:
   *          application/json:
   *            schema:
   *              $ref: '#/components/schemas/Task'
   *      responses:
   *        201:
   *          content:
   *            application/json:
   *              description: tasks
   *              schema:
   *                $ref: '#/components/schemas/Task'
   */
  router.post('/', (req, res) => {

    const incoming = req.body;

    const task = app.models.tasks(incoming);

    task
      .save(incoming)
      .then(doc => res.status(201).json(doc))
      .catch(sendError(res));
  });

  /**
   *  @swagger
   *  /tasks/{id}:
   *    delete:
   *      tags:
   *        - Tasks
   *      description: Delete a task by id
   *      parameters:
   *        - in: path
   *          name: id
   *          description: id of task to be deleted
   *          schema:
   *            type: string
   *      responses:
   *        200:
   *          content:
   *            application/json:
   *              description: tasks
   *              schema:
   *                $ref: '#/components/schemas/Task'
   */
  router.delete('/:id', (req, res) => {
    console.log('about to delete', req.params.id);
    app.models.tasks.findByIdAndRemove(req.params.id)
      .then(doc => {
        console.log('deleted', doc);
        res.json(doc)
      })
      .catch(sendError(res));
  });

  return router;
};

function sendError(res) {
  return error => {
    res.status(500);
    res.send(error);
  }
}
      
    

Docs for Swagger are here. Can use JSON or YAML.

Mark swagger annotations with @swagger

Path is added to url from the servers objects.

Nest everything under the verb.

Request body

Parameter in path

Parameters docs(query, path, header, body, or form):
https://swagger.io/docs/specification/describing-parameters/

$refs are reusable pointers. Here they point to model definitions. Let's look at those.

Models

      
'use strict';

const mongoose = require('mongoose');

module.exports = (app) => {

    app.services.logger.debug('Tasks Model Loaded');

    /**
     *  @swagger
     *  components:
     *    schemas:
     *      Task:
     *        type: object
     *        properties:
     *          title:
     *            type: string
     *          done:
     *            type: boolean
     */
    const tasksSchema = mongoose.Schema({
        title: String,
        done: {
            type: Boolean,
            default: false
        }
    });

    return app.connection.model('Tasks', tasksSchema);
};
      
    

Creating $refs

$ref: '#/components/schemas/Task'

There is some repetition here.

API Keys

      
'use strict';

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

module.exports = server => {


    const options = {
        swaggerDefinition: {
            openapi: "3.0.0",
            info: {
                title: 'Todo API', // Title (required)
                version: '0.0.0', // Version (required)
            },
            servers:  [
              {
                url: '/api/v1',
                description: 'Local Server'
              },
              {
                url: 'https://www.example.com/api/v1',
                description: 'Production Server'
              }
            ],
            security: [
              {
                api_key: []
              }
            ],
            tags: [
              {
                name: "Tasks",
                description: "Things to do."
              }
            ]
        },
        apis: ['./boot/autoload.js', './models/**/*.model.js', './api/**/*.controller.js'], // Path to the API docs
    };

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

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

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

};
      
    

API Keys

        
'use strict';

const consign = require('consign');
const flatten = require('flat');
const logger = require('../services/logger')();

module.exports = (server, connection) => {

    const app = {
        connection
    };

    consign()
        .include('services')
        .include('models')
        .include('api')
        .into(app);

  /**
   *  @swagger
   *  components:
   *    securitySchemes:
   *      api_key:
   *        type: apiKey
   *        in: header
   *        name: X-API-KEY
   */
    // Add controllers to the server
    const flattened = flatten(app.api);
    Object.entries(flattened).forEach(([route, router]) => {
        route = '/api/' + route.replace(/\.controller$/, '').replace(/\./g, '/');
        logger.debug(`mounting router at: ${route}`);
        server.use(route, router);
    });

  // Remove .model from the keys.
    // Needs to be updated if models are put into sub directories
    Object.entries(app.models).forEach(([modelKey, model]) => {
        app.models[modelKey.replace(/.model$/,'')] = model;
    });

    return app;
};
        
      

What it looks like

Protect your API

Let's find an npm

Test it out

          
const limiter = rateLimit({
  windowMs: 15 * 1000, // 15 seconds
  max: 5 // limit each IP to 5 requests per windowMs
});
          
        

Visualize the Problem

Example - 4 requests a day

• What many npms allow
• Limit is completely reset at end of window
• Windows are independent of requests
• Essentially 2X planned requests in 1 second
  • Imagine this with a 500 request limit

Visualize the Problem

          
// export an API to allow hits all IPs to be reset
this.resetAll = function() {
  hits = {};
  resetTime = calculateNextResetTime(windowMs);
};

// simply reset ALL hits every windowMs
const interval = setInterval(this.resetAll, windowMs);
//
          
        

Solution

Rolling Windows

4 requests a day

• Any given window can have only 4 requests

Implementation: Option 1

• Tokens represent credits for calls
• An API call removes a token
• Tokens replenished one at a time at rate limit

Implementation: Option 2