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

Latest commit

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Sinatra::SwaggerExposer

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

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

Todo

  • More parameters taken into account
  • More validations where possible

License

This software is released under the MIT license.

About

Create Swagger endpoint for your Sinatra application

Resources

License

Languages

You can’t perform that action at this time.