Extends fleek-router to use multiple swagger spec versions
Last updated 5 years ago by raymondbutcher .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install fleek-versioned-router 
SYNC missed versions from official npm registry.


Koa middleware that automatically handles routing, validation, and documentation for multiple Swagger spec versions.

This extends fleek-router to use multiple Swagger spec files simultaneously.

Each Swagger spec file should have a different version and basePath value. Requests for different versions can be made incorporating the basePath into the URL, or by sending an X-Api-Version header.

For example, with basePath: /api/1.0.0 in a Swagger spec:

  • curl http://localhost:3000/api/1.0.0/pet/1
  • curl -H "X-Api-Version: 1.0.0" http://localhost:3000/pet/1


npm install --save fleek-versioned-router


See the example directory for an example project.

const glob = require('glob'),
      koa = require('koa'),
      path = require('path'),
      router = require('fleek-versioned-router');

const app = koa();
const specs = glob.sync(path.join(__dirname, 'specs', '*.json'));
const controllers = path.join(__dirname, 'controllers')

    swaggerVersions: specs,  // swagger spec filenames
    controllers: controllers,  // controllers directory
    documentation: true, // swagger-ui documentation
    validate: true, // request validation
    models: true // model validation support



Read fleek-router for more about how controllers and routes work.

fleek-versioned-router is able to work because different specs have different values for basePath. The behavior is unknown when paths clash.

In fleek-versioned-router, a controller might be called by more than one Swagger spec. To find out which one was used for a request, access this.fleek.swagger from within the controller.


The configuration options are almost the same as in fleek-router, with some key differences:

  1. Must set config.swaggerVersions instead of config.swagger
  2. Optionally set config.documentation with different options
  3. Optionally set config.models to enable a model validation helper



Rather than setting config.swagger as in fleek-router, use config.swaggerVersions to specify a list of swagger specs.


  • Array - list of paths for the Swagger specs
config.swaggerVersions = ['specs/v1.json', 'specs/v2.json'];



The config.documentation setting is different to fleek-router in order to support multiple spec versions.

Enabling this will provide:

  • documentation root endpoint
    • returns all Swagger spec versions and their relevant URLs as JSON
  • spec file endpoint for each version
    • returns a Swagger spec as JSON
  • swagger-ui endpoint for each version
    • uses swagger-ui for browsing/testing a Swagger spec version


  • Boolean - if set to true, enables documentation with default paths
  • Object - specify custom paths
// true defaults to the following:
config.documentation = {
    root: '/api',
    docs: '/docs/:version', // :version gets substituted
    spec: '/api/:version' // :version gets substituted



Enable this to add a model validation helper function to the controller context.


  • Boolean - if set to true, enables the model validation helper

usage in controllers

Call this.fleek.validateModel(modelName, data) from a controller to validate and return model data, or return a validation error response if the data was not allowed by the current spec.

this.body = this.fleek.validateModel('User', {
    id: 1,
    name: 'Douglas Quaid'


This option is the same as in fleek-router but an example for fleek-versioned-router may be useful.


config.middleware = function*(next) {
    // Add shortcuts for the relevant spec version.
    this.spec = this.fleek.swagger;
    this.version = this.spec.info.version;
    this.model = this.fleek.validateModel;
    yield next;


To work on fleek-versioned-router, check out the code and then run:

npm install
npm test
npm start

There are also Make commands, see the Makefile to find out more.


  1. Fork the repository
  2. Create a branch
  3. Make your changes, with tests
  4. Run tests with npm test
  5. Submit a pull request


This has been brought to you by Canary and Bashton.

Current Tags

  • 0.0.4                                ...           latest (5 years ago)

2 Versions

  • 0.0.4                                ...           5 years ago
  • 0.0.3                                ...           5 years ago
Maintainers (1)
Today 0
This Week 0
This Month 1
Last Day 0
Last Week 1
Last Month 0
Dependencies (10)
Dev Dependencies (5)
Dependents (1)

Copyright 2014 - 2016 © taobao.org |