swaggerize-express

swaggerize-express is a design-driven approach to building RESTful apis with Swagger and Express.

swaggerize-express provides the following features:

• API schema validation.
• Routes based on the Swagger document.
• API documentation route.
• Input validation.

See also:

• swaggerize-routes
• swaggerize-hapi
• generator-swaggerize

Why "Design Driven"

There are already a number of modules that help build RESTful APIs for node with swagger. However, these modules tend to focus on building the documentation or specification as a side effect of writing the application business logic.

swaggerize-express begins with the swagger document first. This facilitates writing APIs that are easier to design, review, and test.

Quick Start with a Generator

This guide will let you go from an api.json to a service project in no time flat.

First install generator-swaggerize (and yo if you haven't already):

1$ npm install -g yo
2$ npm install -g generator-swaggerize

Now run the generator.

1$ mkdir petstore && cd $_
2$ yo swaggerize

Follow the prompts (note: make sure to choose express as your framework choice).

When asked for a swagger document, you can try this one:

https://raw.githubusercontent.com/wordnik/swagger-spec/master/examples/v2.0/json/petstore.json

You now have a working api and can use something like Swagger UI to explore it.

Manual Usage

1var swaggerize = require('swaggerize-express');
2
3app.use(swaggerize({
4    api: require('./api.json'),
5    docspath: '/api-docs',
6    handlers: './handlers'
7}));

Options:

• api - a valid Swagger 2.0 document.
• docspath - the path to expose api docs for swagger-ui, etc. Defaults to /.
• handlers - either a directory structure for route handlers or a premade object (see Handlers Object below).
• express - express settings overrides.

After using this middleware, a new property will be available on the app called swagger, containing the following properties:

• api - the api document.
• routes - the route definitions based on the api document.

Example:

1var http = require('http');
2var express = require('express');
3var swaggerize = require('swaggerize-express');
4
5app = express();
6
7var server = http.createServer(app);
8
9app.use(swaggerize({
10    api: require('./api.json'),
11    docspath: '/api-docs',
12    handlers: './handlers'
13}));
14
15server.listen(port, 'localhost', function () {
16    app.swagger.api.host = server.address().address + ':' + server.address().port;
17});

Mount Path

Api path values will be prefixed with the swagger document's basePath value.

Handlers Directory

The options.handlers option specifies a directory to scan for handlers. These handlers are bound to the api paths defined in the swagger document.

handlers
  |--foo
  |    |--bar.js
  |--foo.js
  |--baz.js

Will route as:

foo.js => /foo
foo/bar.js => /foo/bar
baz.js => /baz

Path Parameters

The file and directory names in the handlers directory can also represent path parameters.

For example, to represent the path /users/{id}:

1handlers
2  |--users
3  |    |--{id}.js

This works with directory names as well:

1handlers
2  |--users
3  |    |--{id}.js
4  |    |--{id}
5  |        |--foo.js

To represent /users/{id}/foo.

Handlers File

Each provided javascript file should export an object containing functions with HTTP verbs as keys.

Example:

1module.exports = {
2    get: function (req, res) { ... },
3    put: function (req, res) { ... },
4    ...
5}

Handler Middleware

Handlers can also specify middleware chains by providing an array of handler functions under the verb:

1module.exports = {
2    get: [
3        function m1(req, res, next) { ... },
4        function m2(req, res, next) { ... },
5        function handler(req, res)  { ... }
6    ],
7    ...
8}

Handlers Object

The directory generation will yield this object, but it can be provided directly as options.handlers.

Note that if you are programatically constructing a handlers obj this way, you must namespace HTTP verbs with $ to avoid conflicts with path names. These keys should also be lowercase.

Example:

1{
2    'foo': {
3        '$get': function (req, res) { ... },
4        'bar': {
5            '$get': function (req, res) { ... },
6            '$post': function (req, res) { ... }
7        }
8    }
9    ...
10}

Handler keys in files do not have to be namespaced in this way.

Security Middleware

If a security definition exists for a path in the swagger API definition, and an appropriate authorize function exists (defined using x-authorize in the securityDefinitions as per swaggerize-routes), then it will be used as middleware for that path.

In addition, a requiredScopes property will be injected onto the request object to check against.

For example:

Swagger API definition:

1    .
2    .
3    .
4
5    //A route with security object.
6    "security": [
7        {
8            "petstore_auth": [
9                "write_pets",
10                "read_pets"
11            ]
12        }
13    ]
14    .
15    .
16    .
17    //securityDefinitions
18    "securityDefinitions": {
19        "petstore_auth": {
20            "x-authorize": "lib/auth_oauth.js", // This path has to be relative to the project root.
21            "scopes": {
22                "write_pets": "modify pets in your account",
23                "read_pets": "read your pets"
24            }
25        }
26    },

Sample x-authorize code - lib/auth_oauth.js :

1//x-authorize: auth_oauth.js
2function authorize(req, res, next) {
3    validate(req, function (error, availablescopes) {
4        /*
5         * `req.requiredScopes` is set by the `swaggerize-express` module to help
6         * with the scope and security validation.
7         *
8         */
9        if (!error) {
10            for (var i = 0; i < req.requiredScopes.length; i++) {
11                if (availablescopes.indexOf(req.requiredScopes[i]) > -1) {
12                    next();
13                    return;
14                }
15            }
16
17            error = new Error('Do not have the required scopes.');
18            error.status = 403;
19
20            next(error);
21            return;
22        }
23
24        next(error);
25    });
26}

The context for authorize will be bound to the security definition, such that:

1function authorize(req, res, next) {
2    this.authorizationUrl; //from securityDefinition for this route's type.
3    //...
4}