empia / swaggins

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

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.

Prepare the docs folder

At this point I assume you have the JSON definition, so just run

$ swaggins doc

to get your JSON definition and swagger-ui in docs/.

Serve

Show your API docs

$ swaggins serve

This will run the server on port 8080, if you want to change that just pass the port as argument

$ swaggins serve 3000