class SoberSwag::Controller::Route

Describe a single controller endpoint.

Attributes

action_name[R]

The name of the rails action (usually the controller method) of this route. @return [Symbol]

method[R]

The HTTP method of this route. @return [Symbol]

path[R]

The swagger path specifier of this route. @return [String]

path_params_class[R]

What to parse the path params into. @return [Class] a swagger-able class type for path parameters.

query_params_class[R]

What to parse the request query_params into. @return [Class] a swagger-able class type for query parameters.

request_body_class[R]

What to parse the request body into. @return [Class] a swagger-able class type for a request body.

response_descriptions[R]

A hash of response code -> response description @return [Hash{Symbol => String}]

response code to response description
response_serializers[R]

A hash of response code -> response serializer @return [Hash{Symbol => SoberSwag::Serializer::Base}]

response code to response serializer

Public Class Methods

new(method, action_name, path) click to toggle source

@param method [Symbol] the HTTP method to get @param action_name [Symbol] the name of the rails action

(the name of the controller method, usually)

@param path [String] an OpenAPI V3 path template,

which should [match this format](https://swagger.io/docs/specification/describing-parameters/#path-parameters)
# 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

Public Instance Methods

action_module() click to toggle source

The container module for all the constants this will eventually define. Each class generated by this Route will be defined within this module. @return [Module] the module under which constants will be defined.

# File lib/sober_swag/controller/route.rb, line 174
def action_module
  @action_module ||= Module.new
end
action_module_name() click to toggle source

What you should call the module of this action in your controller. @return [String]

# File lib/sober_swag/controller/route.rb, line 216
def action_module_name
  action_name.to_s.classify
end
description(desc = nil) click to toggle source

@overload description()

Get a description of this route object.
@return [String] markdown-formatted description

@overload description(desc)

Set the description of this route object.
@param desc [String] markdown-formatted description
@return [String] `desc`.
# File lib/sober_swag/controller/route.rb, line 150
def description(desc = nil)
  return @description if desc.nil?

  @description = desc
end
path_params(base = SoberSwag::InputObject, reporting: false, &block) click to toggle source

@overload path_params(base)

Give a Swagger-able type that will be used to parse the path params, and used in generated docs.
@param base [Class] a swagger-able class

@overload path_params(base = SoberSwag::InputObject, &block)

Define a Swagger-able type inline to use to parse the path params.
@see SoberSwag.input_object

@overload path_params(base = SoberSwag::Reporting::Input::Struct, reporting: true, &block)

Define a swagger-able type inline, using the new reporting system.
@see SoberSwag::Reporting::Input::Struct
# 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?() click to toggle source

Does this route have path params defined?

# File lib/sober_swag/controller/route.rb, line 138
def path_params?
  !path_params_class.nil?
end
query_params(base = SoberSwag::InputObject, reporting: false, &block) click to toggle source

@overload query_params(base)

Give a Swagger-able type that will be used to parse the query params, and used in generated docs.
@param base [Class] a swagger-able class

@overload query_params(base = SoberSwag::InputObject, &block)

Define a Swagger-able type inline to use to parse the query params.
@see SoberSwag.input_object

@overload query_params(base = SoberSwag::Reporting::Input::Struct, reporting: true, &block)

Define a swagger-able type inline, using the new reporting system.
@see SoberSwag::Reporting::Input::Struct
# 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?() click to toggle source

Does this route have query params defined?

# File lib/sober_swag/controller/route.rb, line 117
def query_params?
  !query_params_class.nil?
end
request_body(base = SoberSwag::InputObject, reporting: false, &block) click to toggle source

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 {SoberSwag::InputObject}.) @overload request_body(base)

Give a Swagger-able type that will be used to parse the request body, and used in generated docs.
@param base [Class] a swagger-able class

@overload request_body(base = SoberSwag::InputObject, &block)

Define a Swagger-able type inline to use to parse the request body.
@see SoberSwag.input_object

@overload request_body(base = SoberSwag::Reporting::Input::Struct, reporting: true, &block)

Define a swagger-able type inline, using the new reporting system.
@see SoberSwag::Reporting::Input::Struct
# 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?() click to toggle source

Does this route have a body defined?

# File lib/sober_swag/controller/route.rb, line 96
def request_body?
  !request_body_class.nil?
end
response(status_code, description, serializer = nil, &block) click to toggle source

@overload response(status_code, description, &block)

Define a new response from this route, by defining a serializer inline.
This serializer will be defined as if with {SoberSwag::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.
@param status_code [Symbol]
  the name of the HTTP status of this response.
@param description [String]
  a description of what this response is, markdown-formatted
@param block [Proc]
  passed to {SoberSwag::OutputObject.define}

@overload response(status_code, description, serializer)

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

@param status_code [Symbol]
  the name of the HTTP status of this response
@param description [String]
  a description of what this response is, markdown-formatted
@param serializer [SoberSwag::Serializer::Base] a serializer to use for the
  body of this response
# 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
summary(sum = nil) click to toggle source

@overload summary()

Get the summary of this route object, a short string that identifies
what it does.
@return [String] markdown-formatted summary

@overload summary(sum)

Set a short, markdown-formatted summary of what this route does.
@param sum [String] markdown-formatted summary
# File lib/sober_swag/controller/route.rb, line 164
def summary(sum = nil)
  return @summary if sum.nil?

  @summary = sum
end
tags(*args) click to toggle source

Standard swagger tags.

@overload tags()

Get the tags for this route.
@return [Array<String,Symbol>] the tags.

@overload tags(*args)

Set the tags for this route.
@param tags [Array<String,Symbol>] the tags to set
@return [Array<String,Symbol>] the tags used
# File lib/sober_swag/controller/route.rb, line 71
def tags(*args)
  return @tags if args.empty?

  @tags = args.flatten
end

Private Instance Methods

make_input_class(base, block) click to toggle source
# 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) click to toggle source
# 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) click to toggle source
# 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) click to toggle source
# 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) click to toggle source
# 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
response_module() click to toggle source
# 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