Class: SoberSwag::Controller::Route

Inherits:
Object
  • Object
show all
Defined in:
lib/sober_swag/controller/route.rb

Overview

Describe a single controller endpoint.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(method, action_name, path) ⇒ Route

Returns a new instance of Route.

Parameters:

  • method (Symbol) —

    the HTTP method to get

  • action_name (Symbol) —

    the name of the rails action (the name of the controller method, usually)

  • path (String) —

    an OpenAPI V3 path template, which should match this format



12
13
14
15
16
17
18
19
 
# File 'lib/sober_swag/controller/route.rb', line 12

def initialize(method, action_name, path)
  @method = method
  @path = path
  @action_name = action_name
  @response_serializers = {}
  @response_descriptions = {}
  @tags = []
end

Instance Attribute Details

#action_name ⇒ Symbol (readonly)

The name of the rails action (usually the controller method) of this route.

Returns:

  • (Symbol) 


46
47
48
 
# File 'lib/sober_swag/controller/route.rb', line 46

def action_name
  @action_name
end

#method ⇒ Symbol (readonly)

The HTTP method of this route.

Returns:

  • (Symbol) 


36
37
38
 
# File 'lib/sober_swag/controller/route.rb', line 36

def method
  @method
end

#path ⇒ String (readonly)

The swagger path specifier of this route.

Returns:

  • (String) 


41
42
43
 
# File 'lib/sober_swag/controller/route.rb', line 41

def path
  @path
end

#path_params_class ⇒ Class (readonly)

What to parse the path params into.

Returns:

  • (Class) —

    a swagger-able class type for path parameters.



59
60
61
 
# File 'lib/sober_swag/controller/route.rb', line 59

def path_params_class
  @path_params_class
end

#query_params_class ⇒ Class (readonly)

What to parse the request query_params into.

Returns:

  • (Class) —

    a swagger-able class type for query parameters.



55
56
57
 
# File 'lib/sober_swag/controller/route.rb', line 55

def query_params_class
  @query_params_class
end

#request_body_class ⇒ Class (readonly)

What to parse the request body into.

Returns:

  • (Class) —

    a swagger-able class type for a request body.



51
52
53
 
# File 'lib/sober_swag/controller/route.rb', line 51

def request_body_class
  @request_body_class
end

#response_descriptions ⇒ Hash{Symbol => String} (readonly)

A hash of response code -> response description

Returns:

  • (Hash{Symbol => String}) —

    response code to response description



31
32
33
 
# File 'lib/sober_swag/controller/route.rb', line 31

def response_descriptions
  @response_descriptions
end

#response_serializers ⇒ Hash{Symbol => SoberSwag::Serializer::Base} (readonly)

A hash of response code -> response serializer

Returns:



25
26
27
 
# File 'lib/sober_swag/controller/route.rb', line 25

def response_serializers
  @response_serializers
end

Instance Method Details

#action_module ⇒ Module

The container module for all the constants this will eventually define. Each class generated by this Route will be defined within this module.

Returns:

  • (Module) —

    the module under which constants will be defined.



174
175
176
 
# File 'lib/sober_swag/controller/route.rb', line 174

def action_module
  @action_module ||= Module.new
end

#action_module_name ⇒ String

What you should call the module of this action in your controller.

Returns:

  • (String) 


216
217
218
 
# File 'lib/sober_swag/controller/route.rb', line 216

def action_module_name
  action_name.to_s.classify
end

#description ⇒ String #description(desc) ⇒ String

Overloads:

  • #description ⇒ String

    Get a description of this route object.

    Returns:

    • (String) —

      markdown-formatted description

  • #description(desc) ⇒ String

    Set the description of this route object.

    Parameters:

    • desc (String) —

      markdown-formatted description

    Returns:

    • (String) —

      desc.



150
151
152
153
154
 
# File 'lib/sober_swag/controller/route.rb', line 150

def description(desc = nil)
  return @description if desc.nil?

  @description = desc
end

#make_input_class(base, block) ⇒ Object (private) 



263
264
265
266
267
268
269
270
271
 
# File 'lib/sober_swag/controller/route.rb', line 263

def make_input_class(base, block)
  if block
    Class.new(base, &block).tap do |e|
      e.transform_keys(&:to_sym) if [SoberSwag::InputObject, Dry::Struct].include?(base)
    end
  else
    base
  end
end

#make_input_object!(base, reporting:, &block) ⇒ Object (private) 



226
227
228
229
230
231
232
233
234
235
 
# File 'lib/sober_swag/controller/route.rb', line 226

def make_input_object!(base, reporting:, &block)
  if reporting
    make_reporting_input!(
      base == SoberSwag::InputObject ? SoberSwag::Reporting::Input::Struct : base,
      &block
    )
  else
    make_non_reporting_input!(base, &block)
  end
end

#make_non_reporting_input!(base, &block) ⇒ Object (private) 



253
254
255
256
257
258
259
260
261
 
# File 'lib/sober_swag/controller/route.rb', line 253

def make_non_reporting_input!(base, &block)
  if base.is_a?(Class)
    make_input_class(base, block)
  elsif block
    raise ArgumentError, 'passed a non-class base and a block to an input'
  else
    base
  end
end

#make_reporting_input!(base, &block) ⇒ Object (private) 



237
238
239
240
241
242
243
244
245
 
# File 'lib/sober_swag/controller/route.rb', line 237

def make_reporting_input!(base, &block)
  if block
    raise ArgumentError, 'non-class passed along with block' unless base.is_a?(Class)

    make_reporting_input_struct!(base, &block)
  else
    base
  end
end

#make_reporting_input_struct!(base, &block) ⇒ Object (private)

Raises:

  • (ArgumentError) 


247
248
249
250
251
 
# File 'lib/sober_swag/controller/route.rb', line 247

def make_reporting_input_struct!(base, &block)
  raise ArgumentError, 'base class must be a soberswag reporting class!' unless base <= SoberSwag::Reporting::Input::Struct

  Class.new(base, &block)
end

#path_params(base) ⇒ Object #path_params(base = SoberSwag::InputObject, &block) ⇒ Object #path_params(base = SoberSwag::Reporting::Input::Struct, reporting: true, &block) ⇒ Object

Overloads:

  • #path_params(base) ⇒ Object

    Give a Swagger-able type that will be used to parse the path params, and used in generated docs.

    Parameters:

    • base (Class) —

      a swagger-able class

  • #path_params(base = SoberSwag::InputObject, &block) ⇒ Object

    Define a Swagger-able type inline to use to parse the path params.

    See Also:

  • #path_params(base = SoberSwag::Reporting::Input::Struct, reporting: true, &block) ⇒ Object

    Define a swagger-able type inline, using the new reporting system.

    See Also:



131
132
133
134
 
# File 'lib/sober_swag/controller/route.rb', line 131

def path_params(base = SoberSwag::InputObject, reporting: false, &block)
  @path_params_class = make_input_object!(base, reporting: reporting, &block)
  action_module.const_set('PathParams', @path_params_class)
end

#path_params? ⇒ Boolean

Does this route have path params defined?

Returns:

  • (Boolean) 


138
139
140
 
# File 'lib/sober_swag/controller/route.rb', line 138

def path_params?
  !path_params_class.nil?
end

#query_params(base) ⇒ Object #query_params(base = SoberSwag::InputObject, &block) ⇒ Object #query_params(base = SoberSwag::Reporting::Input::Struct, reporting: true, &block) ⇒ Object

Overloads:

  • #query_params(base) ⇒ Object

    Give a Swagger-able type that will be used to parse the query params, and used in generated docs.

    Parameters:

    • base (Class) —

      a swagger-able class

  • #query_params(base = SoberSwag::InputObject, &block) ⇒ Object

    Define a Swagger-able type inline to use to parse the query params.

    See Also:

  • #query_params(base = SoberSwag::Reporting::Input::Struct, reporting: true, &block) ⇒ Object

    Define a swagger-able type inline, using the new reporting system.

    See Also:



110
111
112
113
 
# File 'lib/sober_swag/controller/route.rb', line 110

def query_params(base = SoberSwag::InputObject, reporting: false, &block)
  @query_params_class = make_input_object!(base, reporting: reporting, &block)
  action_module.const_set('QueryParams', @query_params_class)
end

#query_params? ⇒ Boolean

Does this route have query params defined?

Returns:

  • (Boolean) 


117
118
119
 
# File 'lib/sober_swag/controller/route.rb', line 117

def query_params?
  !query_params_class.nil?
end

#request_body(base) ⇒ Object #request_body(base = SoberSwag::InputObject, &block) ⇒ Object #request_body(base = SoberSwag::Reporting::Input::Struct, reporting: true, &block) ⇒ Object

Define the request body, using SoberSwag's type-definition scheme. The block passed will be used to define the body of a new subclass of base (defaulted to InputObject.)

Overloads:

  • #request_body(base) ⇒ Object

    Give a Swagger-able type that will be used to parse the request body, and used in generated docs.

    Parameters:

    • base (Class) —

      a swagger-able class

  • #request_body(base = SoberSwag::InputObject, &block) ⇒ Object

    Define a Swagger-able type inline to use to parse the request body.

    See Also:

  • #request_body(base = SoberSwag::Reporting::Input::Struct, reporting: true, &block) ⇒ Object

    Define a swagger-able type inline, using the new reporting system.

    See Also:



89
90
91
92
 
# File 'lib/sober_swag/controller/route.rb', line 89

def request_body(base = SoberSwag::InputObject, reporting: false, &block)
  @request_body_class = make_input_object!(base, reporting: reporting, &block)
  action_module.const_set('RequestBody', @request_body_class)
end

#request_body? ⇒ Boolean

Does this route have a body defined?

Returns:

  • (Boolean) 


96
97
98
 
# File 'lib/sober_swag/controller/route.rb', line 96

def request_body?
  !request_body_class.nil?
end

#response(status_code, description, &block) ⇒ Object #response(status_code, description, serializer) ⇒ Object

Overloads:

  • #response(status_code, description, &block) ⇒ Object

    Define a new response from this route, by defining a serializer inline. This serializer will be defined as if with OutputObject.define

    Generally, you want to define your serializers elsewhere for independent testing and such. However, if you have a really quick thing to serialize, this works.

    Parameters:

    • status_code (Symbol) —

      the name of the HTTP status of this response.

    • description (String) —

      a description of what this response is, markdown-formatted

    • block (Proc) —

      passed to OutputObject.define

  • #response(status_code, description, serializer) ⇒ Object

    Define a new response from this route, with an existing serializer. The generated swagger will document this response's format using the serializer.

    Parameters:

    • status_code (Symbol) —

      the name of the HTTP status of this response

    • description (String) —

      a description of what this response is, markdown-formatted

    • serializer (SoberSwag::Serializer::Base) —

      a serializer to use for the body of this response

Raises:

  • (ArgumentError) 


202
203
204
205
206
207
208
209
210
211
 
# File 'lib/sober_swag/controller/route.rb', line 202

def response(status_code, description, serializer = nil, &block)
  status_key = Rack::Utils.status_code(status_code)

  raise ArgumentError, 'Response defined!' if @response_serializers.key?(status_key)

  serializer ||= SoberSwag::OutputObject.define(&block)
  response_module.const_set(status_code.to_s.classify, serializer)
  @response_serializers[status_key] = serializer
  @response_descriptions[status_key] = description
end

#response_module ⇒ Object (private) 



222
223
224
 
# File 'lib/sober_swag/controller/route.rb', line 222

def response_module
  @response_module ||= Module.new.tap { |m| action_module.const_set(:Response, m) }
end

#summary ⇒ String #summary(sum) ⇒ Object

Overloads:

  • #summary ⇒ String

    Get the summary of this route object, a short string that identifies what it does.

    Returns:

    • (String) —

      markdown-formatted summary

  • #summary(sum) ⇒ Object

    Set a short, markdown-formatted summary of what this route does.

    Parameters:

    • sum (String) —

      markdown-formatted summary



164
165
166
167
168
 
# File 'lib/sober_swag/controller/route.rb', line 164

def summary(sum = nil)
  return @summary if sum.nil?

  @summary = sum
end

#tags ⇒ Array<String,Symbol> #tags(*args) ⇒ Array<String,Symbol>

Standard swagger tags.

Overloads:

  • #tags ⇒ Array<String,Symbol>

    Get the tags for this route.

    Returns:

    • (Array<String,Symbol>) —

      the tags.

  • #tags(*args) ⇒ Array<String,Symbol>

    Set the tags for this route.

    Parameters:

    • tags (Array<String,Symbol>) —

      the tags to set

    Returns:

    • (Array<String,Symbol>) —

      the tags used



71
72
73
74
75
 
# File 'lib/sober_swag/controller/route.rb', line 71

def tags(*args)
  return @tags if args.empty?

  @tags = args.flatten
end