Up-to-date documentation for your Node.js REST API
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!
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
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": ""// One or more renderering modes// And their associated options"renderers":"<name>":"<name>":
See each renderer for the set of available options:
In the HTML renderer, the first few levels of
describe() statements make up the navigation sidebar.
Your markdown content
it() statements can contain valid Markdown, which make up the description of each example.
- The request headers, including custom ones. However it excludes typically irrelevant headers for the context of documentation (
accept-encoding: gzip, deflate,
- The request payload & attachements.
- 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 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.
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: