v0.7.1
swagginsServe 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.jshttp.request
once at the top of your testextract
: passingres
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 intox-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:
;
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.
extract
Pass res
only where you need:
var extract = extract; ;
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