Module: RESTFramework::Mixins::BaseControllerMixin

Included in:

BaseModelControllerMixin

Defined in:

lib/rest_framework/mixins/base_controller_mixin.rb

Overview

This module provides the common functionality for any controller mixins, a ‘root` action, and the ability to route arbitrary actions with `extra_actions`. This is also where `render_api` is implemented.

Defined Under Namespace

Modules: ClassMethods

Constant Summary

RRF_BASE_CONFIG =

{
  extra_actions: nil,
  extra_member_actions: nil,
  singleton_controller: nil,

  # Options related to metadata and display.
  title: nil,
  description: nil,
  version: nil,
  inflect_acronyms: [ "ID", "IDs", "REST", "API", "APIs" ].freeze,
  openapi_include_children: false,

  # Options related to serialization.
  rescue_unknown_format_with: :json,
  serializer_class: nil,
  serialize_to_json: true,
  serialize_to_xml: true,

  # Options related to pagination.
  paginator_class: nil,
  page_size: 20,
  page_query_param: "page",
  page_size_query_param: "page_size",
  max_page_size: nil,

  # Option to disable serializer adapters by default, mainly introduced because Active Model
  # Serializers will do things like serialize `[]` into `{"":[]}`.
  disable_adapters_by_default: true,

  # Custom integrations (reduces serializer performance due to method calls).
  enable_action_text: false,
  enable_active_storage: false,
}

Class Method Summary

• .included(base) ⇒ Object

Instance Method Summary

• #get_serializer_class ⇒ Object
• #openapi_document ⇒ Object
• #options ⇒ Object
• #render_api(payload, **kwargs) ⇒ Object (also: #api_response)

  Render a browsable API for ‘html` format, along with basic `json`/`xml` formats, and with support or passing custom `kwargs` to the underlying `render` calls.

• #root ⇒ Object

  Default action for API root.

• #route_groups ⇒ Object
• #rrf_error_handler(e) ⇒ Object
• #serialize(data, **kwargs) ⇒ Object

  Serialize the given data using the ‘serializer_class`.

Class Method Details

.included(base) ⇒ Object

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 189

def self.included(base)
  return unless base.is_a?(Class)

  base.extend(ClassMethods)

  # By default, the layout should be set to `rest_framework`.
  base.layout("rest_framework")

  # Add class attributes unless they already exist.
  RRF_BASE_CONFIG.each do |a, default|
    next if base.respond_to?(a)

    # Don't leak class attributes to the instance to avoid conflicting with action methods.
    base.class_attribute(a, default: default, instance_accessor: false)
  end

  # Alias `extra_actions` to `extra_collection_actions`.
  unless base.respond_to?(:extra_collection_actions)
    base.singleton_class.alias_method(:extra_collection_actions, :extra_actions)
    base.singleton_class.alias_method(:extra_collection_actions=, :extra_actions=)
  end

  # Skip CSRF since this is an API.
  begin
    base.skip_before_action(:verify_authenticity_token)
  rescue
    nil
  end

  # Handle some common exceptions.
  unless RESTFramework.config.disable_rescue_from
    base.rescue_from(
      ActionController::ParameterMissing,
      ActionController::UnpermittedParameters,
      ActionDispatch::Http::Parameters::ParseError,
      ActiveRecord::AssociationTypeMismatch,
      ActiveRecord::NotNullViolation,
      ActiveRecord::RecordNotFound,
      ActiveRecord::RecordInvalid,
      ActiveRecord::RecordNotSaved,
      ActiveRecord::RecordNotDestroyed,
      ActiveRecord::RecordNotUnique,
      ActiveModel::UnknownAttributeError,
      with: :rrf_error_handler,
    )
  end

  # Use `TracePoint` hook to automatically call `rrf_finalize`.
  if RESTFramework.config.auto_finalize
    # :nocov:
    TracePoint.trace(:end) do |t|
      next if base != t.self

      base.rrf_finalize

      # It's important to disable the trace once we've found the end of the base class definition,
      # for performance.
      t.disable
    end
    # :nocov:
  end
end

Instance Method Details

#get_serializer_class ⇒ Object

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 252

def get_serializer_class
  self.class.serializer_class
end

#openapi_document ⇒ Object

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 361

def openapi_document
  first, *rest = self.route_groups.to_a
  document = self.class.openapi_document(request, *first)

  if self.class.openapi_include_children
    rest.each do |route_group_name, routes|
      controller = "#{routes.first[:route].defaults[:controller]}_controller".camelize.constantize
      child_document = controller.openapi_document(request, route_group_name, routes)

      # Merge child paths and tags into the parent document.
      document[:paths].merge!(child_document[:paths])
      document[:tags] += child_document[:tags]

      # If the child document has schemas, merge them into the parent document.
      if schemas = child_document.dig(:components, :schemas)  # rubocop:disable Style/Next
        document[:components] ||= {}
        document[:components][:schemas] ||= {}
        document[:components][:schemas].merge!(schemas)
      end
    end
  end

  document
end

#options ⇒ Object

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 386

def options
  render(api: self.openapi_document)
end

#render_api(payload, **kwargs) ⇒ Object Also known as: api_response

Render a browsable API for ‘html` format, along with basic `json`/`xml` formats, and with support or passing custom `kwargs` to the underlying `render` calls.

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 287

def render_api(payload, **kwargs)
  html_kwargs = kwargs.delete(:html_kwargs) || {}
  json_kwargs = kwargs.delete(:json_kwargs) || {}
  xml_kwargs = kwargs.delete(:xml_kwargs) || {}

  # Raise helpful error if payload is nil. Usually this happens when a record is not found (e.g.,
  # when passing something like `User.find_by(id: some_id)` to `render_api`). The caller should
  # actually be calling `find_by!` to raise ActiveRecord::RecordNotFound and allowing the REST
  # framework to catch this error and return an appropriate error response.
  if payload.nil?
    raise RESTFramework::NilPassedToRenderAPIError
  end

  # If `payload` is an `ActiveRecord::Relation` or `ActiveRecord::Base`, then serialize it.
  if payload.is_a?(ActiveRecord::Base) || payload.is_a?(ActiveRecord::Relation)
    payload = self.serialize(payload)
  end

  # Do not use any adapters by default, if configured.
  if self.class.disable_adapters_by_default && !kwargs.key?(:adapter)
    kwargs[:adapter] = nil
  end

  # Flag to track if we had to rescue unknown format.
  already_rescued_unknown_format = false

  begin
    respond_to do |format|
      if payload == ""
        format.json { head(kwargs[:status] || :no_content) } if self.class.serialize_to_json
        format.xml { head(kwargs[:status] || :no_content) } if self.class.serialize_to_xml
      else
        format.json {
          render(json: payload, **kwargs.merge(json_kwargs))
        } if self.class.serialize_to_json
        format.xml {
          render(xml: payload, **kwargs.merge(xml_kwargs))
        } if self.class.serialize_to_xml
        # TODO: possibly support more formats here if supported?
      end
      format.html {
        @payload = payload
        if payload == ""
          @json_payload = "" if self.class.serialize_to_json
          @xml_payload = "" if self.class.serialize_to_xml
        else
          @json_payload = payload.to_json if self.class.serialize_to_json
          @xml_payload = payload.to_xml if self.class.serialize_to_xml
        end
        @title ||= self.class.get_title
        @description ||= self.class.description
        self.route_groups
        begin
          render(**kwargs.merge(html_kwargs))
        rescue ActionView::MissingTemplate
          # A view is not required, so just use `html: ""`.
          render(html: "", layout: true, **kwargs.merge(html_kwargs))
        end
      }
    end
  rescue ActionController::UnknownFormat
    if !already_rescued_unknown_format && rescue_format = self.class.rescue_unknown_format_with
      request.format = rescue_format
      already_rescued_unknown_format = true
      retry
    else
      raise
    end
  end
end

#root ⇒ Object

Default action for API root.

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 40

def root
  render(api: { message: "This is the API root." })
end

#route_groups ⇒ Object

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 281

def route_groups
  @route_groups ||= RESTFramework::Utils.get_routes(Rails.application.routes, request)
end

#rrf_error_handler(e) ⇒ Object

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 263

def rrf_error_handler(e)
  status = case e
  when ActiveRecord::RecordNotFound
    404
  else
    400
  end

  render(
    api: {
      message: e.message,
      errors: e.try(:record).try(:errors),
      exception: RESTFramework.config.show_backtrace ? e.full_message : nil,
    }.compact,
    status: status,
  )
end

#serialize(data, **kwargs) ⇒ Object

Serialize the given data using the ‘serializer_class`.

# File 'lib/rest_framework/mixins/base_controller_mixin.rb', line 257

def serialize(data, **kwargs)
  RESTFramework::Utils.wrap_ams(self.get_serializer_class).new(
    data, controller: self, **kwargs
  ).serialize
end