module SoberSwag::Controller

This module can be included in any subclass of `ActionController` or `ActionController::API` to make it `SoberSwag`-able. This means that you can use the mechanics of SoberSwag to define a type-safe API, with generated Swagger documentation!

Public Instance Methods

body_params() click to toggle source

Obtain a parameters hash of only those parameters which come in the hash. These will be unsafe in the sense that they will all be allowed. This kinda violates the “be liberal in what you accept” principle, but it keeps the docs honest: parameters sent in the body must be in the body.

@return [Hash]

# File lib/sober_swag/controller.rb, line 174
def body_params
  request.request_parameters
end
build_parsed_sober_swag(parser, params) click to toggle source
# File lib/sober_swag/controller.rb, line 186
def build_parsed_sober_swag(parser, params)
  if parser.respond_to?(:call!)
    parser.call!(params)
  else
    parser.call(params)
  end
end
current_action_def() click to toggle source

Get the action-definition for the current action. Under the hood, delegates to the `:action` key of rails params. @return [SoberSwag::Controller::Route]

# File lib/sober_swag/controller.rb, line 182
def current_action_def
  self.class.find_route(params[:action])
end
parsed_body() click to toggle source

Get the request body, parsed into the type you defined with {SoberSwag::Controller::ClassMethods#define}. @raise [UndefinedBodyError] if there's no request body defined for this route @raise [Dry::Struct::Error] if we cannot convert the path params to the defined type.

# File lib/sober_swag/controller.rb, line 125
def parsed_body
  @parsed_body ||=
    begin
      r = current_action_def
      raise UndefinedBodyError unless r&.request_body_class

      build_parsed_sober_swag(r.request_body_class, body_params)
    end
end
parsed_path() click to toggle source

Get the path parameters, parsed into the type you defined with {SoberSwag::Controller::ClassMethods#define} @raise [UndefinedPathError] if there's no path params defined for this route @raise [Dry::Struct::Error] if we cannot convert the path params to the defined type.

# File lib/sober_swag/controller.rb, line 111
def parsed_path
  @parsed_path ||=
    begin
      r = current_action_def
      raise UndefinedPathError unless r&.path_params_class

      build_parsed_sober_swag(r.path_params_class, request.path_parameters)
    end
end
parsed_query() click to toggle source

Get the query params, parsed into the type you defined with {SoberSwag::Controller::ClassMethods#define} @raise [UndefinedQueryError] if there's no query params defined for this route @raise [Dry::Struct::Error] if we cannot convert the path params to the defined type.

# File lib/sober_swag/controller.rb, line 139
def parsed_query
  @parsed_query ||=
    begin
      r = current_action_def
      raise UndefinedQueryError unless r&.query_params_class

      build_parsed_sober_swag(r.query_params_class, request.query_parameters)
    end
end
respond!(status, entity, serializer_opts: {}, rails_opts: {}) click to toggle source

Respond with the serialized type that you defined for this route. @todo figure out how to specify views and other options for the serializer here @param status [Symbol] the HTTP status symbol to use for the status code @param entity the thing to serialize

# File lib/sober_swag/controller.rb, line 154
def respond!(status, entity, serializer_opts: {}, rails_opts: {})
  r = current_action_def
  serializer = r.response_serializers[Rack::Utils.status_code(status)]
  if serializer.respond_to?(:reporting?) && serializer.reporting?
    serializer = serializer.view(serializer_opts[:view].to_sym) if serializer_opts.key?(:view)
    render json: serializer.call(entity), status: status, **rails_opts
  else
    serializer ||= serializer.new if serializer.respond_to?(:new)
    render json: serializer.serialize(entity, serializer_opts), status: status, **rails_opts
  end
end
swagger() click to toggle source

ActiveController action to get the swagger definition for this API. It renders a JSON of the OpenAPI v3 schema for this API.

# File lib/sober_swag/controller.rb, line 103
def swagger
  render json: self.class.swagger_info
end