Documentation and samples for your Node.js RESTful API
- define concrete request/response examples in your test suite
- if you need to, use mocks to make sure you fully control the API responses
- add a few explanations in Markdown
- choose from a few output formats
- get high-level API documentation that's always up-to-date!
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!
What will the docs look like?
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.
How do I set it up?
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:
What goes in the docs?
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
Supersamples instruments every request that goes through supertest by default. If you are making multiple requests per
it, sometimes the results can be a bit problematic as request and responses get merged.
You can explicitly ignore certain requests from being captured by setting the following header
Ignoring whole tests
Perhaps you include you docs specs in the same tests as other integration tests that you don't want appearing in your docs
You can exclude them with the following
- The request headers, including custom ones. However it excludes typically irrelevant headers for the context of documentation (
accept-encoding: gzip, deflate,
- The request payload & file attachments.
- The response status code, regardless of any
- 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 actually 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.
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 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.