lazywithclass / swaggins

swaggins v0.7.1

Have a look at an auto generated example Swagger doc, no manual changes required!

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

Information extracted includes:

• path of the endpoint
• method(s) that the endpoint supports
• statusCode returned by the call to the endpoint
• body either passed to the endpoint (via POST) for example, or received from the endpoint

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