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.
- 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
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.
A more complete example is available here.
- 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.