node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


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.