Collection of samples for your Node.js REST API

npm install supersamples
22 downloads in the last day
51 downloads in the last week
171 downloads in the last month


Documentation and samples for your Node.js RESTful API

NPM version Build Status

supersamples is a Mocha reporter that understands Supertest to generate reliable and up-to-date API samples. In a nutshell:

  • define concrete request/response examples in your test suite
  • if you need to, use mocks to make sure you fully control the API reponses
  • add a few explanations in Markdown
  • get high-level API documentation that's always up-to-date!

See a live example over here.

Works with any Node.js http.Server, like Express or Restify

So what will my tests look like?

Nothing special! Simply use supertest in your test suite, and supersamples will generate the request/response documentation for you!

it '''
# Get list of sports
- list is ordered alphabetically
- doesn't return sports with no active competitions
''', (done) ->

    .set('Accept', 'application/json')
    .expect('Content-Type', /json/)
      sports: [
        { id: 1, name: 'Soccer' }
        { id: 2, name: 'Tennis' }

What goes in the docs?

The navigation & markdown

  • The first 2 levels of describe() statements make up the navigation sidebar.
  • Each section then includes the it() definition as a Markdown description of the example.

The request

  • The request headers, including custom ones. However it excludes typically irrelevant headers for the context of documentation (accept-encoding: gzip, deflate, host: http://localhost:1234...).
  • The request payload, if present.

The response

  • The response status code, regardless of any expect().
  • The response headers, but only if they were mentioned in expect(). The reason is that many frameworks will add dozens of default headers, which could seriously clutter the docs.
  • The actualy response body, regardless of any expect(). Note that even if they don't affect the docs, expectations are checked during the generation process. We 100% recommend that you add some to give extra confidence that the HTTP response are correct.

How do I set it up?

npm install supersamples --save

Have a look at the example folder to get started. You can add tests to the usual test folder, or keep them separate if you want. Simply run Mocha with the provided reporter:

./node_modules/.bin/mocha --reporter supersamples path/to/tests

You can specify documentation options in a separate supersamples.opts file at the root. This file has to be valid JSON, but also supports comments:


  // Documentation page title

  "title": "My API docs",

  // Optional Markdown document used at the top of the docs
  // Heading levels 1 and 2 are appended to the navigation

  "intro": "tests/",

  // Base URL used in the CURL examples

  "baseUrl": "",

  // Output folder

  "output": "docs",

  // Extra files to be copied into the output folder (css, logos, htaccess...)
  // <key> is a glob pattern to a list of files
  // <value> is the target folder inside of the configured output

  "files": {
    "tests/extra/**": "."

  // Paths to custom CSS files, to override the default styles
  // These must have been copied as part of "files"

  "styles": [


What doesn't it do?

supersamples DOES NOT provide a way to describe every path or query string parameter. It's meant to give you reliable but low-cost API samples. If you want a very detailled API description, you might like other tools better:

    - tools like Apiary or ApiDoc let you document your API in text-format (for example Markdown or JavaScript comments). Just remember to keep these up to date!

    - tools like Swagger provide a JavaScript API to define your routes. It can generate docs that are always up-to-date, if you don't mind using their syntax instead of vanilla Express or Restify.


Issues & pull requests welcome.

To work on the project locally, simply run:

# install dependencies
npm install

# allow supersamples to require itself
npm link
npm link supersamples

# run the unit tests
npm test

# build the example
make clean example-docs

# deploy the example docs to Github pages
make deploy
npm loves you