Swaggins serves Swagger docs from your integration tests, no need to maintain both, because YOLO.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples/express
lib
test
.gitignore
CHANGELOG.md
LICENSE
Makefile
README.md
cli.js
index.js
package.json

README.md

swaggins v0.7.1

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

Dependency Status dev dependencies peer dependencies

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

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