Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.
Swagger-Jack is a nodeJS modules that implements the swagger specification and offers you three middlewares to:
First, get the module, by referencing it inside your package.json:
"dependencies":"express": "3.1.0""swagger-jack": "1.0.0"
Then, when creating your Express application, import and configure the two middlewares:
var express =swagger = ;var app = ;app
Generator takes the following parameters:
A "resource" is composed by a resource descriptor, and the corresponding code (what we called controller).
The middleware will automatically add to your express application the routes found inside the resource descriptor, and bound them to the provided controller (it uses the
nickname attribute from the descriptor to bound the right controller's method).
In the previous example, two routes are created:
POST /api/user/to create a user (controller method
GET /api/user/to list existing users (controller method
As explained in the swagger specification, the descriptor
basePath attribute is used as url prefix for every resources and their operations.
You should not repeat it in resources paths and apis path.
resourcePath in resource object is intended to be repeated in every api path.
If you just want to document some existing routes, just provide a resource descriptor, and no associated controller. Of course, no validation will be provided.
You can still register routes and middleware within your application, like you've used to. But they will not be documented nor validated.
The following options are available:
String: path of generated swagger descriptor. Must contain leading slash. Default to
basePathused as prefix.
Validator will analyze the declared parameters of your descriptor, and validate the input. It will handle parameter casting, range validation and declared model compliance (thank to the excellent json-gate).
All casted values (except body parameters) are available inside the controller methods with the
req.input associative array.
No matter if parameter is from path, query or header: it will be present inside
You can still use the Express original function (
req.headers...), but beware: values are just strings.
Bodies are also validated, but parsing is done by express's bodyParser middleware: it takes in account json and multipart bodies. For other bodies kind, validator will read itself the body, and perfoms casting.
Caution You must use
Caution You can't read the body by yourself (with data/end request events) for routes declared with
If you do not need validation, no problem: just remove the validator middleware.
Validation errors (and your custom business errors) are handled by the error middleware. It uses the express's error mecanism: invoke the next() method with an argument.
Weither it's a string or an object, it will be serialized into a json response with an http status (500 by default).
Input validation errors are reported the same way.
You may not use the error middleware and provide your own.
Use js-yaml to store your descriptor in a separate file, and split your code into other controller modules:
var express =swagger =yaml = ;var app = ;app
For very specific cases, it's possible to use the validation function without request.
// init your application as usualvar app = ;var validator; // don't init yet ! the generator was not invokedapp
You still need to use an Express application and to declare generator and validator middlewares.
Documentation for the
validate() function can be found in the source code
To be Done
Reverb folks (the ones who made Swagger) provide an express module to enhance your Express application by returning the swagger descriptor.
It provides a quick way to describe your code in Json and register your express routes. To me it's very handy for a start, but has three problems:
Swagger is shipped with an MIT Licence.
Copyright (c) 2013 Atos Worldline
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
We looked for a fun and yet eloquent name. But swagger.js was already used. Jack Swagger is an american catch superstar, and we never heard about him before, but it perfectly fits your naming goals :)