My first

Multi-language Bot!

Juan David Nicholls

Software Engineer

@ BevyUp (Acquired by Nordstrom)

We need something simple, but scalable...

We need to document our APIs...

How can I autodocument my endpoints from the code?

var swaggerUi = require('swagger-ui-express');
var swagger = require('swagger-spec-express');

We add some packages...

Initialize Swagger

swagger.initialise(app, {
  title: 'MY REST API',
  version: '1.0.0',
  description: 'This is a REST API for MyBot app',
  contact: {
    email: 'jdnichollsc@hotmail.com'
  },
  securityDefinitions: {
    bearerAuth: {
      type: "apiKey",
      name: "Authorization",
      description: "HTTP Bearer Authentication"
    }
  },
  defaultSecurity: "bearerAuth",
});

We can even define our authentication based on JWT tokens, etc ...

We add our endpoints...

app.use('/users', userRoute);
app.use('/auth', authRoute);
//...
app.get('/swagger.json', function (err, res) {
  res.status(200).json(swagger.json());
});
app.use('/', swaggerUi.serve, swaggerUi.setup(null, {
  swaggerUrl: '/swagger.json',
  swaggerOptions: {
    validatorUrl : null
  }
}));
swagger.compile();

And finally we describe our routes from the code

var express = require('express');
var router = express.Router();
var swagger = require('swagger-spec-express');
swagger.swaggerize(router);

swagger.common.addTag({
  name: "Auth",
  description: "Operations about authentication"
});
router.post('/login', async function (req, res, next) {
  //code code code
}).describe({
  tags: ["Auth"],
  summary: "Authenticate the user",
  description: "Validate if exist an user with that email and password",
  consumes: ["application/json"],
  produces: ["application/json"],
  parameters: [
    {
      name: "body",
      in: "body",
      schema: {
        type: "object",
        properties: {
          email: { type: "string", format: "email" },
          password: { type: "string" }
        }
      }
    }
  ],
  responses: {
    200: {
      description: "Returns the token and the info of the user"
    },
    404: {
      description: "The user doesn't exist with that email and password"
    }
  }
});
router.post('/signup', async function (req, res, next) {
  //code code code
}).describe({
  tags: ["Auth"],
  summary: "Register a new user",
  description: "Create a new user from the app",
  consumes: ["application/json"],
  produces: ["application/json"],
  parameters: [
    {
      name: "body",
      in: "body",
      schema: {
        $ref: "#/definitions/User"
      }
    }
  ],
  responses: {
    200: {
      description: "Returns the token and the info of the user"
    },
    500: {
      description: "Returns an error trying to create a new user"
    }
  }
});

Additionally we can create our own definitions

swagger.common.addModel({
  "name": "User",
  "type": "object",
  "properties": {
    "document": { "type": "string" },
    "name": { "type": "string" },
    "cellPhone": { "type": "string" },
    "homePhone": { "type": "string" },
    "email": { "type": "string", "format": "email" },
    "password": { "type": "string" }
  }
});

And we definitely need to reach our users

MyBot to the rescue!

Made with Slides.com