Swaggins NPM | npm.io

swaggins v0.7.1

Serve Swagger docs from your integration tests, no need to maintain both, because YOLO.

### How

Swaggins extracts useful information for your Swagger docs from Node.js HTTP res object.

Install

-g is optional, you might want to do it for when you use swaggins from the CLI.

$ npm install swaggins

Usage

Have a look at the express example but ideally you would have to do the following steps

configure your tests
run your tests, so you get the JSON swagger definition
prepare the docs folder with the JSON
serve your docs

Configure your tests

There are two ways to do so:

probe: proxying Node.js http.request once at the top of your test
extract: passing res everytime you need

If you need to pass in extra information that you want to be added to the documentation you could use the following headers:

x-swaggins-endpoint-description - the endpoint description, will be at the top under "Implementation Notes"
x-swaggins-status-description - the status description, will be under "Response Class"
x-swaggins-tag - dictates in which group this endpoint will fall into
x-swaggins-path - uses what you provide as path, so you could have a URL that reads like '/api/answers/{answer-id}' or simply '/api/answers{id}', as you prefer

If you want to ignore a call just add x-swaggins-ignore to your headers.

probe

Include this line at the top of your test and you're good to go:

require('swaggins').probe();

It makes sense to include it just once for all your test, it proxies http.request so there's no reason to do it twice.

Example

extract

Pass res only where you need:

var extract = require('swaggins').extract;

it('answers to /answer with 42', function(done) {
  request(
    'http://localhost:3000/answer/everything',
    function cb(err, res, body) {
      extract(res); <--- here is where we use swaggins
      expect(body).to.equal('42');
      done();
    }
  );
});

Example

Run your tests

In the examples folder I've provided a very basic example, Swaggins expects you to run your integration tests against a real server, so that it can get res and extract the information.