Westfield Swagger

Overview

Westfield Swagger is a mountable Rails engine which provides everything needed to create and serve Swagger 2.0 API specifications & documentation.

Installation

Add it to your Gemfile:

gem 'westfield_swagger'

Then bundle:

$ bundle install

Usage

WestfieldSwagger will add a new route at /swagger which provides three things:

1. An API endpoint allowing access to the swagger at '/swagger/.json'
2. An HTML endpoint at '/swagger/'
3. An API endpoint allowing access to the swagger at '/swagger//.json'
4. An HTML endpoint at '/swagger//'

External routing for (1, 2) access the swagger in api.xxx.westfield.io or secure.xxx.westfield.io. This is the swagger rollup of all the services.

External routing to the service endpoint for (3, 4) accesses the swagger for the service where the gem is installed. The JavaScript executes without the service in the path, thus loading as in (2).

Your specification can be fully-formatted in JSON at lib/swagger/{version}.json or in YAML with embedded Ruby (ERB) at lib/swagger/{version}.yml. This will be converted to JSON on-demand when requested. For (1, 2) in the uat and production environments, it prefixes the swagger path version with the environment, so the filename is, for example, uat_1.json.

Additionally, the swagger files can be split across files and directories and will be reconstructed on the fly.

To generate the required files, run:

$ rails generate swagger

This will add an example specification (lib/swagger/0.1.yml), example tests (spec/requests/swagger_spec.rb) and will mount the engine in your routes.rb file.

References

• Swagger: http://swagger.io/
• Specs (2.0): https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md