Documentation and samples for your Node.js RESTful API
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'''requestserverget'/sports'set'Accept''application/json'expect200expect'Content-Type'/json/expectsports:id: 1name: 'Soccer'id: 2name: 'Tennis'enddone
supersamples comes with several renderers built-in:
htmlgenerates a multi-page static HTML website
markdownto generate a single Markdown page you can easily upload to Github
jsonto generate JSON metadata you can process later
postmanto generate a postman collection for your API
See a live example of the HTML output over here.
npm install supersamples --save-dev
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 also need to specify documentation options in a supersamples.opts file at the root. This file has to be valid
JSON, but also supports comments:
// Base URL for the API"baseUrl": ""// Mocha reporter to display test results// e.g. Dot, TAP, Spec..."reporter": "Dot"// One or more rendering modes// And their associated options"renderers":"<name>": ..."<name>": ...
See each renderer for the set of available options:
Well it depends on the renderer you choose, but they all work off the same set of data:
The nested suite of
describe() statements that lead to your test becomes the hierarchy / breadcrumbs. In the HTML renderer, the first 2 levels make up the navigation sidebar.
Your markdown content
it() statements can contain valid Markdown, which make up the description of each example.
A name for each sample
By default, the content of the
it also becomes your sample name. This is used in the
JSON renderer to help you identify samples. You can also override the name with
it 'gets a list of sports' done ->@supersamples = name: 'valid list'
accept-encoding: gzip, deflate,
expect(). The reason is that many frameworks will add dozens of default headers, which could seriously clutter the docs.
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.
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 detailed API description, you might like other tools better:
In our current project, we actually use
supersamples together to generate formal API specs as well as request/response examples, and display both side by side in our API portal.