Skip to content
This repository has been archived by the owner. It is now read-only.
Branch: master
Go to file

Latest commit


Failed to load latest commit information.
Latest commit message
Commit time


Code Climate Build Status Coverage Status

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


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

          version: '0.0.1',
          title: 'My app',
          description: 'My wonderful app',
          license: {
              name: 'MIT',
              url: ''

  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'})


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'})

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


Changelog is here.



  • More parameters taken into account
  • More validations where possible


This software is released under the MIT license.


Create Swagger endpoint for your Sinatra application




You can’t perform that action at this time.