sans-server-swagger

Table of Contents

• Example
• Configuration
• Helper Methods

- req.deserialize
    - [.binary](#reqdeserializebinary)
    - [.byte](#reqdeserializebyte)
    - [.date](#reqdeserializedate)
    - [.dateTime](#reqdeserializedatetime)
- req.swagger    
    - [.rel](#reqswaggerrel)
    - [.root](#reqswaggerroot)
- [res.enforce](#resenforce)
- res.swagger
    - [.example](#resswaggerexample)
    - [.enforce](#resswaggerenforce)

• Controllers
• Mocks

- [Validation](#validation)
- [Mock Sources](#mock-sources)
- [Automatic vs Manual Mocking](#automatic-vs-manual-mocking)
- [Test Response Examples](#test-response-examples)

• Swagger Enforcer

- [Response Enforcement](#response-enforcement)

Example

const Server = require('sans-server');
const Swagger = require('sans-server-swagger');
const Router = require('sans-server-router');

// define the server
const server = Server();

// define the swagger middleware with a router
const swaggerMiddleware = Swagger({
    controllers: './controllers',
    development: true,
    exception: function(res, state) {
        res.body({
            status: state.statusCode,
            message: state.body
        });
    },
    swagger: './swagger.json'
});

// use the swagger middleware
server.use(swaggerMiddleware);

// make a request against the server
server.request({ method: 'GET', path: '/v1/path/to/call' })
    .then(function(res) {
        console.log(res.statusCode);
        console.log(res.body);
    });

Configuration

• controllers - REQUIRED The directory path to JavaScript files that contain the methods to execute to fulfill web service requests.

• development - OPTIONAL If true then mocks will automatically be produced from examples when a controller does not exist. Additionally not all controllers must exist. If set to false then all controller implementations must exist. Defaults to false.

• exception - OPTIONAL A function that will get called if the middleware is unable to provide an expected response. This function will receive two parameters: 1) res - the response object, and 2) state - the current response state data. Use the response object to make any modifications to the response before it is returned.

This function will be called when 1) the response does not meet the response schema defined by swagger, 2) the response uses a status code that is not defined by swagger, 3) the request has invalid input, and 4) when a response is not implemented.

• ignoreBasePath - OPTIONAL If true then the swagger base path will not be used in the routes. Defaults to false.

• mockQueryParameter - OPTIONAL The query parameter to look for when a response should be manually mocked. Defaults to mock.

• swagger - REQUIRED The swagger file that defines the services. This can be either a json or a yaml file.

Helper Methods

req.deserialize.binary

• value - An 8-bit binary string made of 0s and 1s.

const buffer = req.deserialize.binary('00000010');

req.deserialize.byte

• value - A base64 encoded string.

const buffer = req.deserialize.binary('aGVsbG8=');

req.deserialize.date

• value - A date string, formatted as YYYY-MM-DD.

const date = req.deserialize.date('2000-01-01');

req.deserialize.dateTime

• value - An ISO date string.

const date = req.deserialize.dateTime('2000-01-01T00:00:00.000Z');

req.swagger.rel

const swagger = req.swagger.rel;

req.swagger.root

const swagger = req.swagger.root;

res.enforce

res.swagger.example

const result = res.swagger.example(200);

const result = res.swagger.enforce(200);

1. You need a directory where you will place all of your controller files. This directory is specified by the controller option when creating the middleware.

```js
const swaggerMiddleware = Swagger({
    controllers: './controllers',
    ...
});
```

1. Each path's controller implementation is defined by it's x-controller and operationId.

- `x-controller` is the name of the file within the controllers directory that implements the function defined by the `operationId`. The `x-controller` can be defined for the entire swagger document, for a specific path, or for a specific method within a path by defining this property at those different levels within your swagger document. An `x-controller` defined at one level can be overwritten by another `x-controller` at a more specific level.

- `operationId` is the name of the property within your controller that has the function to execute. This function will receive as parameters the sans-server request and response objects.

**For example purposes only**, in the following example the `x-controller` is defined at the document level, the path level, and the method level. In actuality, the `x-controller` only needs to be defined at each appropriate level once. If defined at the document level then all paths and methods will use that controller unless a specific path or method has an `x-controller` specified as something else.

```yaml
x-controller: pets              # All methods for all paths will use pets.js controller unless overwritten
paths:
  "/pets":
    x-controller: pets          # This path will use the pets.js controller for all methods within this path unless overwritten
    get:
      x-controller: pets        # This method within this path will use the pets.js controller
      summary: List all pets
      operationId: listPets     # Implementation looked for in exports.listPets in pets.js file
```

Mocks

Validation

Mock Sources

1. From examples within the swagger document:

```yaml
paths:
  "/pets":
    get:
      summary: List all pets
      operationId: listPets
      responses:
        '200':
          description: An paged array of pets
          examples:
            application/json:     # Mocks will be produced from examples
            - id: 123
              name: Sparky
              tag: Dog
            - id: 456
              name: Ghost
              tag: Cat
            - id: 789
              name: Goldy
              tag: Fish
          schema:
            "$ref": "#/definitions/Pets"
```

1. From an implemented mock in a controller:

```js
// until this implementation is complete we can have it call the custom mock
exports.listPets = function(req, res) {
    exports.listPets.mock(req, res);     // call the mock
};

// a custom mock for this implementation
exports.listPets.mock = function(req, res) {
    res.send([
        {
            id: 123,
            name: "Sparky",
            tag: "Dog"
        },
        {
            id: 456,
            name: "Ghost",
            tag: "Cat"
        },
        {
            id: 789,
            name: "Goldy",
            tag: "Fish"
        }
    ]);
};
```

Automatic vs Manual Mocking

1. The configuration must have the development option set to true.

1. There must be no implementation for the endpoint being hit.

1. There must be a mock source.

1. The swagger definition for the path being mocked must specify the mocked query parameter as a swagger query parameter.

1. The incoming request has a query parameter that matches the mocked query parameter.

1. There must be a mock source.

Testing Response Examples

sans-server-swagger ./swagger.yaml

const expect = require('chai').expect;
const Swagger = require('sans-server-swagger');

describe('my tests', () => {
    it('examples are valid', () => {
        return Swagger.testSwaggerResponseExamples('./swagger.yaml')
            .then(results => expect(results.percentage).to.equal(1));
    });
});

const Swagger = require('sans-server-swagger');
const test = require('tape');

test('my tests', t => {
    t.plan(1);
    Swagger.testSwaggerResponseExamples('./swagger.yaml')
        .then(results => t.equal(results.percentage, 1));
});

Swagger Enforcer

const Swagger = require('sans-server-swagger');
const Enforcer = Swagger.Enforcer;

const date = Enforcer.to.date(new Date());
console.log(date);      // a string of "2000-01-01" (or whatever the date actually is)

Response Enforcement

exports.foo = function(req, res) {
    const result = res.enforce(200);    // 200 - the response code to enforce
    result.firstName = 'Bob';           // an error will be thrown here if this is an invalid mutation of the result
    result.lastName = 'Smith';          // an error will be thrown here if this is an invalid mutation of the result
    res.send(result);
};

exports.foo = function(req, res) {
    const result = res.enforce(200, { firstName: 'Bob' });  // will throw an error here if initial value is invalid
    result.lastName = 'Smith';          // an error will be thrown here if this is an invalid mutation of the result
    res.send(result);
};