Module: Sinatra::SwaggerExposer

Defined in:
lib/sinatra/swagger-exposer/swagger-exposer.rb,
lib/sinatra/swagger-exposer/version.rb,
lib/sinatra/swagger-exposer/swagger-content-creator.rb,
lib/sinatra/swagger-exposer/swagger-parameter-helper.rb,
lib/sinatra/swagger-exposer/swagger-invalid-exception.rb,
lib/sinatra/swagger-exposer/configuration/swagger-info.rb,
lib/sinatra/swagger-exposer/configuration/swagger-type.rb,
lib/sinatra/swagger-exposer/configuration/swagger-types.rb,
lib/sinatra/swagger-exposer/configuration/swagger-endpoint.rb,
lib/sinatra/swagger-exposer/configuration/swagger-hash-like.rb,
lib/sinatra/swagger-exposer/swagger-request-processor-creator.rb,
lib/sinatra/swagger-exposer/configuration/swagger-type-property.rb,
lib/sinatra/swagger-exposer/processing/swagger-request-processor.rb,
lib/sinatra/swagger-exposer/configuration/swagger-response-header.rb,
lib/sinatra/swagger-exposer/processing/swagger-response-processor.rb,
lib/sinatra/swagger-exposer/configuration/swagger-response-headers.rb,
lib/sinatra/swagger-exposer/configuration/swagger-endpoint-response.rb,
lib/sinatra/swagger-exposer/processing/swagger-base-value-processor.rb,
lib/sinatra/swagger-exposer/processing/swagger-processor-dispatcher.rb,
lib/sinatra/swagger-exposer/processing/swagger-type-value-processor.rb,
lib/sinatra/swagger-exposer/configuration/swagger-endpoint-parameter.rb,
lib/sinatra/swagger-exposer/processing/swagger-array-value-processor.rb,
lib/sinatra/swagger-exposer/processing/swagger-file-processor-dispatcher.rb,
lib/sinatra/swagger-exposer/processing/swagger-primitive-value-processor.rb,
lib/sinatra/swagger-exposer/configuration/swagger-configuration-utilities.rb,
lib/sinatra/swagger-exposer/configuration/swagger-parameter-validation-helper.rb

Overview

Expose swagger API from your Sinatra app

Defined Under Namespace

Modules: Configuration, Processing, SwaggerParameterHelper Classes: SwaggerContentCreator, SwaggerInvalidException, SwaggerProcessorCreator

Constant Summary collapse

VERSION = 
'0.5.0'

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.declare_swagger_endpoint(app) ⇒ Object

Declare the endpoint to serve the swagger content

Parameters:

  • app (Sinatra::Base) 


40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/sinatra/swagger-exposer/swagger-exposer.rb', line 40

def self.declare_swagger_endpoint(app)
  app.endpoint_summary 'The swagger endpoint'
  app.endpoint_tags 'swagger'
  app.endpoint_response 200
  app.get('/swagger_doc.json') do
    swagger_content = Sinatra::SwaggerExposer::SwaggerContentCreator.new(
      settings.respond_to?(:swagger_info) ? settings.swagger_info : nil,
      settings.swagger_types,
      settings.swagger_endpoints
    ).to_swagger
    content_type :json
    swagger_content.to_json
  end

  app.endpoint_summary 'Option method for the swagger endpoint, useful for some CORS stuff'
  app.endpoint_tags 'swagger'
  app.endpoint_response 200
  app.endpoint_produces 'text/plain;charset=utf-8'
  app.options('/swagger_doc.json') do
    content_type :text
    200
  end
end

.registered(app) ⇒ Object

Called when we register the extension

Parameters:

  • app (Sinatra::Base) 


21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
 
# File 'lib/sinatra/swagger-exposer/swagger-exposer.rb', line 21

def self.registered(app)
  app.set :result_validation, (ENV['RACK_ENV'] != 'production')
  app.set :swagger_endpoints, []
  app.set :swagger_current_endpoint_info, {}
  app.set :swagger_current_endpoint_parameters, {}
  app.set :swagger_current_endpoint_responses, {}

  swagger_types = Sinatra::SwaggerExposer::Configuration::SwaggerTypes.new
  app.set :swagger_types, swagger_types

  response_headers = Sinatra::SwaggerExposer::Configuration::SwaggerResponseHeaders.new
  app.set :swagger_response_headers, response_headers

  app.set :swagger_processor_creator, Sinatra::SwaggerExposer::SwaggerProcessorCreator.new(swagger_types)
  declare_swagger_endpoint(app)
end

Instance Method Details

#endpoint(params) ⇒ Object

Define fluent endpoint dispatcher

Parameters:

  • params (Hash) —

    the parameters



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/sinatra/swagger-exposer/swagger-exposer.rb', line 110

def endpoint(params)
  params.each_pair do |param_name, param_value|
    case param_name
      when :summary
        endpoint_summary param_value
      when :description
        endpoint_description param_value
      when :tags
        endpoint_tags *param_value
      when :produces
        endpoint_produces *param_value
      when :path
        endpoint_path param_value
      when :parameters
        param_value.each do |param, args_param|
          endpoint_parameter param, *args_param
        end
      when :responses
        param_value.each do |code, args_response|
          endpoint_response code, *args_response
        end
      else
        raise SwaggerInvalidException.new("Invalid endpoint parameter [#{param_name}]")
    end
  end
end

#endpoint_description(description) ⇒ Object

Provide a description for the endpoint

Parameters:

  • description (String) 


78
79
80
 
# File 'lib/sinatra/swagger-exposer/swagger-exposer.rb', line 78

def endpoint_description(description)
  set_if_type_and_not_exist(description, :description, String)
end

#endpoint_parameter(name, description, how_to_pass, required, type, params = {}) ⇒ Object

Define parameter for the endpoint



95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/sinatra/swagger-exposer/swagger-exposer.rb', line 95

def endpoint_parameter(name, description, how_to_pass, required, type, params = {})
  parameters = settings.swagger_current_endpoint_parameters
  check_if_not_duplicate(name, parameters, 'Parameter')
  parameters[name] = Sinatra::SwaggerExposer::Configuration::SwaggerEndpointParameter.new(
    name,
    description,
    how_to_pass,
    required,
    type,
    params,
    settings.swagger_types.types_names)
end

#endpoint_path(path) ⇒ Object

Provide a path

Parameters:

  • path (String) 


72
73
74
 
# File 'lib/sinatra/swagger-exposer/swagger-exposer.rb', line 72

def endpoint_path(path)
  set_if_type_and_not_exist(path, :path, String)
end

#endpoint_produces(*produces) ⇒ Object

Provide produces params for the endpoint

Parameters:

  • produces (Array<String>) —

    the response types



90
91
92
 
# File 'lib/sinatra/swagger-exposer/swagger-exposer.rb', line 90

def endpoint_produces(*produces)
  set_if_not_exist(produces, :produces)
end

#endpoint_response(code, type = nil, description = nil, headers = []) ⇒ Object

Declare a response

Parameters:

  • code (Integer) —

    the response code

  • type (defaults to: nil) —

    the type

  • description (String) (defaults to: nil) —

    the description

  • headers (Array<String>) (defaults to: []) —

    the headers names



157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/sinatra/swagger-exposer/swagger-exposer.rb', line 157

def endpoint_response(code, type = nil, description = nil, headers = [])
  responses = settings.swagger_current_endpoint_responses
  check_if_not_duplicate(code, responses, 'Response')
  responses[code] = Sinatra::SwaggerExposer::Configuration::SwaggerEndpointResponse.new(
    type,
    description,
    settings.swagger_types.types_names,
    headers,
    settings.swagger_response_headers
  )
end

#endpoint_summary(summary) ⇒ Object

Provide a summary for the endpoint

Parameters:

  • summary (String) 


66
67
68
 
# File 'lib/sinatra/swagger-exposer/swagger-exposer.rb', line 66

def endpoint_summary(summary)
  set_if_type_and_not_exist(summary, :summary, String)
end

#endpoint_tags(*tags) ⇒ Object

Provide tags for the endpoint

Parameters:

  • tags (Array<String>) 


84
85
86
 
# File 'lib/sinatra/swagger-exposer/swagger-exposer.rb', line 84

def endpoint_tags(*tags)
  set_if_not_exist(tags, :tags)
end

#general_info(params) ⇒ Object

General information



138
139
140
 
# File 'lib/sinatra/swagger-exposer/swagger-exposer.rb', line 138

def general_info(params)
  set :swagger_info, Sinatra::SwaggerExposer::Configuration::SwaggerInfo.new(params)
end

#response_header(name, type, description) ⇒ Object

Declare a response header



148
149
150
 
# File 'lib/sinatra/swagger-exposer/swagger-exposer.rb', line 148

def response_header(name, type, description)
  settings.swagger_response_headers.add_response_header(name, type, description)
end

#route(verb, path, options = {}, &block) ⇒ Object

Override Sinatra route method



170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/sinatra/swagger-exposer/swagger-exposer.rb', line 170

def route(verb, path, options = {}, &block)
  no_swagger = options[:no_swagger]
  options.delete(:no_swagger)
  if (verb == 'HEAD') || no_swagger
    super(verb, path, options, &block)
  else
    request_processor = create_request_processor(verb.downcase, path, options)
    super(verb, path, options) do |*params|
      response = catch(:halt) do
        request_processor.run(self, params, &block)
      end
      if settings.result_validation
        begin
          # Inspired from Sinatra#invoke
          if (Integer === response) or (String === response)
            response = [response]
          end
          if (Array === response) and (Integer === response.first)
            response_for_validation = response.dup
            response_status = response_for_validation.shift
            response_body = response_for_validation.pop
            response_headers = (response_for_validation.pop || {}).merge(self.response.header)
            response_content_type = response_headers['Content-Type']
            request_processor.validate_response(response_body, response_content_type, response_status)
          elsif response.respond_to? :each
            request_processor.validate_response(response.first.dup, self.response.header['Content-Type'], 200)
          end
        rescue Sinatra::SwaggerExposer::SwaggerInvalidException => e
          content_type :json
          throw :halt, [400, {:code => 400, :message => e.message}.to_json]
        end
      end
      throw :halt, response
    end
  end
end

#type(name, params) ⇒ Object

Declare a type



143
144
145
 
# File 'lib/sinatra/swagger-exposer/swagger-exposer.rb', line 143

def type(name, params)
  settings.swagger_types.add_type(name, params)
end