Sinatra::SwaggerExposer

Create Swagger endpoint for your Sinatra application.

This Sinatra extension enable you to add metadata to your code to

• expose your API as a Swagger endpoint.
• validate and enrich the invocation parameters
• validate the responses during test and development

I'm adding features as I need them and it currently doesn't use all the Swagger options, so if you need one that is missing please open an issue.

Design choices

• All the declarations are validated when the server is started
• The declarations are defined to look as ruby-ish as possible
• Declarations are used for parameters validation and enrichment

Usage

Bring in the 'sinatra-swagger-exposer' gem from rubygems.

To use it in your app :

require 'sinatra/swagger-exposer/swagger-exposer'

class MyApp < Sinatra::Base

  register Sinatra::SwaggerExposer

  general_info(
      {
          version: '0.0.1',
          title: 'My app',
          description: 'My wonderful app',
          license: {
              name: 'MIT',
              url: 'http://opensource.org/licenses/MIT'
          }
      }
  )

  type 'Status',
               {
                   :properties => {
                       :status => {
                           :type => String,
                           :example => 'OK',
                       },
                   },
                   :required => [:status]
               }

  endpoint_description 'Base method to ping'
  endpoint_response 200, 'Status', 'Standard response'
  endpoint_tags 'Ping'
  get '/' do
    json({'status' => 'OK'})
  end

end

The swagger json endpoint will be exposed at /swagger_doc.json.

You can also use a more fluent variant by providing a hash to the endpoint method

  endpoint :description => 'Base method to ping',
           :responses { 200 => ['Status', 'Standard response']}
           :tags 'Ping'
  get '/' do
    json({'status' => 'OK'})
  end

The hash should contains the key description, summary, path, tags, responses and params. Note both responses and params takes a hash as argument hash(param_name =>param_details) and hash(status_code=>res_param)

If the equivalent methods have more than one param, theses are wrapped in an array.

Detailed example

A more complete example is available here.

About swagger-ui

• If you to use swagger-ui with your app you will need to add croo-origin setup. The easiest way is to use the sinatra-cross_origin gem. Fro a simple sample you can have a look at example application.
• Swagger-ui doesn't work with all the swagger features
  • Some of them like parameters maximum and minimum values are ignored
  • Some of them like extending types make the endpoint unusable

Changes

Changelog is here.

Resources

• Swagger RESTful API Documentation Specification.
• Swagger json examples.
• The swagger json schema.

Todo

• More parameters taken into account
• More validations where possible

License

This software is released under the MIT license.