Fork of the popular swagger-node-express module, with added features
JavaScript CSS
Pull request Compare This branch is 9 commits ahead, 491 commits behind swagger-api:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

This is the Wordnik Swagger code for the express framework. For more on Swagger, please visit For more on express, please visit

#Why a different module?

The main motivation behind this module, is that I needed a set of extra features from Swagger, but submitting a Pull Request would take too long.

##What's new?

  • Before method for controllers: Now you can define a before method that will be executed before the action method on the controller specs.(There is also a pull request awaiting approval on the official Github repo.)

  • JSON Schemas to create parameter lists: Swagger now has a new method paramsFromSchema. This method will allow the developer to define a JSON schema to describe the parameters, which in turn, could potentially be used to validate the request.

See below for a code sample of how the before function is defined.

READ MORE about swagger!

See the swagger website or the swagger-core wiki, which contains information about the swagger json spec.

Try a sample! The source for a functional sample is available on github:

Adding swagger to your express-based API

Include swagger.js in your app and add express as the app handler:

var express = require("express")
 , url = require("url")
 , swagger = require("swagger-node-express");

var app = express();


You can optionally add a validator function, which is used to filter the swagger json and request operations:

// This is a sample validator.  It simply says that for _all_ POST, DELETE, PUT  methods, 
// the header api_key OR query param api_key must be equal to the string literal 
// special-key.  All other HTTP ops are A-OK */

  function validate(req, path, httpMethod) {
    //  example, only allow POST for api_key="special-key"
    if ("POST" == httpMethod || "DELETE" == httpMethod || "PUT" == httpMethod) {
      var apiKey = req.headers["api_key"];
      if (!apiKey) {
        apiKey = url.parse(req.url,true).query["api_key"]; }
      if ("special-key" == apiKey) {
        return true; 
      return false;
    return true;

You now add models to the swagger context. Models are described in a JSON format, per the swagger model specification. Most folks keep them in a separate file (see here for an example), or you can add them as such:


Next, add some resources. Each resource contains a swagger spec as well as the action to execute when called. The spec contains enough to describe the method, and adding the resource will do the rest. For example:

var findById = {
  'spec': {
    "description" : "Operations about pets",
    "path" : "/pet.{format}/{petId}",
    "notes" : "Returns a pet based on ID",
    "summary" : "Find pet by ID",
    "method": "GET",
    "params" : [swagger.pathParam("petId", "ID of pet that needs to be fetched", "string")],
    "responseClass" : "Pet",
    "errorResponses" : [swagger.errors.invalid('id'), swagger.errors.notFound('pet')],
    "nickname" : "getPetById"
  'before': funtion(req, res, action) { //Separates validation from the main action code.
     if (!req.params.petId) { //Usefull when validation requires async callbacks.
        throw swagger.errors.invalid('id'); 
     } else {
      action(req, res); //now we call the action
  'action': function (req,res) {
    var id = parseInt(req.params.petId);
    var pet = petData.getPetById(id);

    if(pet) res.send(JSON.stringify(pet));
    else throw swagger.errors.notFound('pet');


Adds an API route to express and provides all the necessary information to swagger.

Finally, configure swagger with a public URL and version:

swagger.configure("", "0.1");

and the server can be started:


Now you can open up a swagger-ui and browse your API, generate a client with swagger-codegen, and be happy.

Other Configurations

.{format} suffix removal

If you don't like the .{format} or .json suffix, you can override this before configuring swagger:

swagger.configureSwaggerPaths("", "/api-docs", "");

That will put the resource listing under /api-docs, and ditch the .{format} on each of the apis you're adding to. Make sure to set the paths correctly in your spec configuration though, like such:

// note the .{format} is removed from the path!
var findById = {
  'spec': {
    "description" : "Operations about pets",
    "path" : "/pet/{petId}",
    "notes" : "Returns a pet based on ID",

Mapping swagger to subpaths

To add a subpath to the api (i.e. list your REST api under /api or /v1), you can configure express as follows:

var app = express();
var subpath = express();

app.use("/v1", subpath);


Now swagger and all apis configured through it will live under the /v1 path (i.e. /v1/api-docs.json).

Allows-origin and special headers

If you want to modify the default headers sent with every swagger-managed method, you can do so as follows:

swagger.setHeaders = function setHeaders(res) {
  res.header('Access-Control-Allow-Origin', "*");
  res.header("Access-Control-Allow-Methods", "GET, POST, DELETE, PUT");
  res.header("Access-Control-Allow-Headers", "Content-Type, X-API-KEY");
  res.header("Content-Type", "application/json; charset=utf-8");

If you have a special name for an api key (such as X-API-KEY, per above), this is where you can inject it.