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 169
def body_params
  request.request_parameters
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 177
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

      r.request_body_class.call(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

      r.path_params_class.call(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

      r.query_params_class.call(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)]
  serializer ||= serializer.new if serializer.respond_to?(:new)
  render json: serializer.serialize(entity, serializer_opts), status: status, **rails_opts
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