Class: Apiwork::Representation::Base

Inherits:

Object

Object
Apiwork::Representation::Base

show all

Includes:: Abstractable

Defined in:: lib/apiwork/representation/base.rb

Overview

Base class for representations.

Defines how an ActiveRecord model is represented in the API. Drives contracts and runtime behavior. Sensible defaults are auto-detected from database columns but can be overridden. Supports STI and polymorphic associations.

Examples:

Basic representation

class InvoiceRepresentation < Apiwork::Representation::Base
  attribute :id
  attribute :title
  attribute :status, filterable: true, sortable: true

  belongs_to :customer
  has_many :items
end

Contract

class InvoiceContract < Apiwork::Contract::Base
  representation InvoiceRepresentation
end

Instance Attribute Summary collapse

#context ⇒ Hash readonly

The serialization context.
#record ⇒ Object readonly

Class Method Summary collapse

.abstract! ⇒ void

Marks this representation as abstract.
.abstract? ⇒ Boolean

Whether this representation is abstract.
.adapter {|adapter| ... } ⇒ void

Configures adapter options for this representation.
.adapter_config ⇒ Object
.api_class ⇒ Object
.associations ⇒ Hash{Symbol => Association}

The associations for this representation.
.attribute(name, decode: nil, default: UNSET, deprecated: false, description: nil, empty: nil, encode: nil, enum: nil, example: nil, filterable: false, format: nil, max: nil, min: nil, nullable: nil, optional: nil, preload: nil, sortable: false, type: nil, writable: false, write_only: false) {|element| ... } ⇒ void

Defines an attribute for this representation.
.attributes ⇒ Hash{Symbol => Attribute}

The attributes for this representation.
.belongs_to(name, deprecated: false, description: nil, example: nil, filterable: false, include: :optional, nullable: nil, polymorphic: nil, representation: nil, sortable: false, writable: false) ⇒ void

Defines a belongs_to association for this representation.
.deprecated! ⇒ void

Marks this representation as deprecated.
.deprecated? ⇒ Boolean

Whether this representation is deprecated.
.description(value = nil) ⇒ String^?

The description for this representation.
.deserialize(payload) ⇒ Hash⁺

Transforms a hash or an array of hashes for records.
.example(value = nil) ⇒ Hash^?

The example value for this representation.
.has_many(name, deprecated: false, description: nil, example: nil, filterable: false, include: :optional, representation: nil, sortable: false, writable: false) ⇒ void

Defines a has_many association for this representation.
.has_one(name, deprecated: false, description: nil, example: nil, filterable: false, include: :optional, nullable: nil, representation: nil, sortable: false, writable: false) ⇒ void

Defines a has_one association for this representation.
.inheritance ⇒ Representation::Inheritance^?

The inheritance configuration for this representation.
.inheritance_for_column(column_name) ⇒ Object
.model(value) ⇒ void

Configures the model class for this representation.
.model_class ⇒ Class<ActiveRecord::Base>

The model class for this representation.
.object(name, deprecated: false, description: nil, example: nil) {|object| ... } ⇒ void

Defines an object type for this representation.
.polymorphic_association_for_type_column(column_name) ⇒ Object
.polymorphic_name ⇒ String

The polymorphic name for this representation.
.preloads ⇒ Object
.root(singular, plural = singular.to_s.pluralize) ⇒ void

Configures the JSON root key for this representation.
.root_key ⇒ RootKey

The root key for this representation.
.serialize(resource, context: {}, include: nil) ⇒ Hash⁺

Transforms a record or an array of records to hashes.
.serialize_record(record, context: {}, include: nil) ⇒ Object
.sti_name ⇒ String

The STI name for this representation.
.subclass? ⇒ Boolean

Whether this representation is an STI subclass.
.type_name(value = nil) ⇒ String^?

The type name for this representation.
.union(name, deprecated: false, description: nil, discriminator: nil, example: nil) {|union| ... } ⇒ void

Defines a union type for this representation.

Instance Method Summary collapse

#as_json ⇒ Object
#initialize(record, context: {}, include: nil) ⇒ Base constructor

A new instance of Base.

Constructor Details

#initialize(record, context: {}, include: nil) ⇒ `Base`

Returns a new instance of Base.

# File 'lib/apiwork/representation/base.rb', line 922

def initialize(record, context: {}, include: nil)
  @record = record
  @context = context
  @include = include
end

Instance Attribute Details

#context ⇒ `Hash` (readonly)

The serialization context.

Passed from controller or directly to serialize. Use for data that isn’t on the record, like current user or permissions.

Examples:

Override in controller

def context
  { current_user: current_user }
end

Access in custom attribute

attribute :editable, type: :boolean

def editable
  context[:current_user]&.admin?
end

Returns:

(Hash)



109
110
111

# File 'lib/apiwork/representation/base.rb', line 109

def context
  @context
end

#record ⇒ `Object` (readonly)



109
110

# File 'lib/apiwork/representation/base.rb', line 109

attr_reader :context,
:record

Class Method Details

.abstract! ⇒ `void`

This method returns an undefined value.

Marks this representation as abstract.

Abstract representations don’t require a model and serve as base classes for other representations. Use this when creating application-wide base representations. Subclasses automatically become non-abstract.

Examples:

Application base representation

class ApplicationRepresentation < Apiwork::Representation::Base
  abstract!
end

# File 'lib/apiwork/representation/base.rb', line 44

class Base
  include Abstractable

  # @!method self.attributes
  #   @api public
  #   The attributes for this representation.
  #
  #   @return [Hash{Symbol => Attribute}]
  class_attribute :attributes, default: {}, instance_accessor: false

  # @!method self.associations
  #   @api public
  #   The associations for this representation.
  #
  #   @return [Hash{Symbol => Association}]
  class_attribute :associations, default: {}, instance_accessor: false

  # @!method self.inheritance
  #   @api public
  #   The inheritance configuration for this representation.
  #
  #   Auto-configured when the model uses STI and representation classes mirror the model hierarchy.
  #   Subclasses share the parent's inheritance configuration.
  #
  #   @return [Representation::Inheritance, nil]
  class_attribute :inheritance, default: nil, instance_accessor: false

  class_attribute :_adapter_config, default: {}, instance_accessor: false
  class_attribute :type_definitions, default: {}, instance_accessor: false

  # @!attribute [r] context
  #   @api public
  #   The serialization context.
  #
  #   Passed from controller or directly to {.serialize}. Use for data that isn't on the record, like
  #   current user or permissions.
  #
  #   @return [Hash]
  #
  #   @example Override in controller
  #     def context
  #       { current_user: current_user }
  #     end
  #
  #   @example Access in custom attribute
  #     attribute :editable, type: :boolean
  #
  #     def editable
  #       context[:current_user]&.admin?
  #     end
  #
  # @!attribute [r] record
  #   @api public
  #   The record for this representation.
  #
  #   Available in custom attributes and associations.
  #
  #   @return [ActiveRecord::Base]
  #
  #   @example Custom attribute
  #     attribute :full_name, type: :string
  #
  #     def full_name
  #       "#{record.first_name} #{record.last_name}"
  #     end
  attr_reader :context,
              :record

  class << self
    # @api public
    # Configures the model class for this representation.
    #
    # Auto-detected from representation name when not set. Use {.model_class} to retrieve.
    #
    # @param value [Class<ActiveRecord::Base>]
    #   The model class.
    # @return [void]
    # @raise [ArgumentError] if value is not an ActiveRecord model class
    #
    # @example
    #   model Invoice
    def model(value)
      unless value.is_a?(Class)
        raise ConfigurationError,
              "model must be an ActiveRecord model class, got #{value.class}. " \
                                                             "Use: model Post (not 'Post' or :post)"
      end
      unless value < ActiveRecord::Base
        raise ConfigurationError,
              "model must be an ActiveRecord model class, got #{value}"
      end
      @model_class = value
    end

    # @api public
    # Configures the JSON root key for this representation.
    #
    # Auto-detected from model name when not set. Use {.root_key} to retrieve.
    #
    # @param singular [String, Symbol]
    #   The singular root key.
    # @param plural [String, Symbol] (singular.pluralize)
    #   The plural root key.
    # @return [void]
    #
    # @example
    #   root :bill, :bills
    def root(singular, plural = singular.to_s.pluralize)
      @root = { plural: plural.to_s, singular: singular.to_s }
    end

    # @api public
    # Configures adapter options for this representation.
    #
    # Overrides API-level options. Subclasses inherit parent adapter options.
    #
    # @yieldparam adapter [Configuration]
    # @return [void]
    #
    # @example
    #   adapter do
    #     pagination do
    #       strategy :cursor
    #       default_size 50
    #     end
    #   end
    def adapter(&block)
      return unless block

      self._adapter_config = _adapter_config.dup
      config = Configuration.new(api_class.adapter_class, _adapter_config)
      block.arity.positive? ? yield(config) : config.instance_eval(&block)
    end

    # @api public
    # Defines an attribute for this representation.
    #
    # Subclasses inherit parent attributes.
    #
    # @param name [Symbol]
    #   The attribute name.
    # @param decode [Proc, nil] (nil)
    #   Transform for request input (API to database). Must preserve the attribute type.
    # @param default [Object] (UNSET)
    #   The default value. Omit to declare no default. Pass `nil` for an explicit null default. If omitted and name maps to a database column, auto-detected from the column's static default.
    # @param deprecated [Boolean] (false)
    #   Whether deprecated. Metadata included in exports.
    # @param description [String, nil] (nil)
    #   The description. Metadata included in exports.
    # @param empty [Boolean, nil] (nil)
    #   Whether to use empty string instead of `null`. Serializes `nil` as `""` and deserializes `""` as `nil`. Only valid for `:string` type.
    # @param encode [Proc, nil] (nil)
    #   Transform for response output (database to API). Must preserve the attribute type.
    # @param enum [Array, nil] (nil)
    #   The allowed values. If `nil`, auto-detected from Rails enum definition.
    # @param example [Object, nil] (nil)
    #   The example. Metadata included in exports.
    # @param filterable [Boolean] (false)
    #   Whether the attribute is filterable.
    # @param format [Symbol, nil] (nil) [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :text, :url, :uuid]
    #   Format hint for exports. Does not change the type, but exports may add validation or
    #   documentation based on it. Valid formats by type: `:decimal`/`:number` (`:double`, `:float`),
    #   `:integer` (`:int32`, `:int64`), `:string` (`:date`, `:datetime`, `:email`, `:hostname`,
    #   `:ipv4`, `:ipv6`, `:password`, `:text`, `:url`, `:uuid`).
    # @param max [Integer, nil] (nil)
    #   The maximum. For `:array`: size. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.
    # @param min [Integer, nil] (nil)
    #   The minimum. For `:array`: size. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.
    # @param nullable [Boolean, nil] (nil)
    #   Whether the value can be `null`. If `nil` and name maps to a database column, auto-detected from column NULL constraint.
    # @param optional [Boolean, nil] (nil)
    #   Whether the attribute is optional for writes. If `nil` and name maps to a database column,
    #   auto-detected from column default or NULL constraint.
    # @param preload [Symbol, Array, Hash, nil] (nil)
    #   Associations to preload for this attribute. Use when custom attributes depend on associations.
    # @param sortable [Boolean] (false)
    #   Whether the attribute is sortable.
    # @param type [Symbol, nil] (nil) [:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :number, :object, :string, :time, :unknown, :uuid]
    #   The type. If `nil` and name maps to a database column, auto-detected from column type.
    #   Defaults to `:unknown` for json/jsonb columns and when no column exists (custom attributes).
    #   Use an explicit type or block in those cases.
    # @param writable [Boolean, Symbol] (false) [:create, :update]
    #   The write access. `true` for both create and update, `:create` for create only, `:update` for update only.
    # @param write_only [Boolean] (false)
    #   Whether the attribute is write-only. Write-only attributes are excluded from response
    #   serialization and response types but remain in writable payloads.
    # @yieldparam element [Representation::Element]
    # @return [void]
    #
    # @example Basic
    #   attribute :title
    #   attribute :price, type: :decimal, min: 0
    #   attribute :status, filterable: true, sortable: true
    #
    # @example Custom attribute with preload
    #   attribute :total, type: :decimal, preload: :items
    #
    #   def total
    #     record.items.sum(:amount)
    #   end
    #
    # @example Nested preload
    #   attribute :total_with_tax, type: :decimal, preload: { items: :tax_rate }
    #
    #   def total_with_tax
    #     record.items.sum { |item| item.amount * (1 + item.tax_rate.rate) }
    #   end
    #
    # @example Inline type for JSON column
    #   attribute :settings do
    #     object do
    #       string :theme
    #       boolean :notifications
    #     end
    #   end
    #
    # @example Encode/decode transforms
    #   attribute :status, encode: ->(value) { value.upcase }, decode: ->(value) { value.downcase }
    #
    # @example Writable only on create
    #   attribute :slug, writable: :create
    #
    # @example Explicit enum values
    #   attribute :priority, enum: [:low, :medium, :high]
    #
    # @example Multiple preloads
    #   attribute :summary, type: :string, preload: [:items, :customer]
    #
    #   def summary
    #     "#{record.customer.name}: #{record.items.count} items"
    #   end
    def attribute(
      name,
      decode: nil,
      default: UNSET,
      deprecated: false,
      description: nil,
      empty: nil,
      encode: nil,
      enum: nil,
      example: nil,
      filterable: false,
      format: nil,
      max: nil,
      min: nil,
      nullable: nil,
      optional: nil,
      preload: nil,
      sortable: false,
      type: nil,
      writable: false,
      write_only: false,
      &block
    )
      self.attributes = attributes.merge(
        name => Attribute.new(
          name,
          self,
          decode:,
          default:,
          deprecated:,
          description:,
          empty:,
          encode:,
          enum:,
          example:,
          filterable:,
          format:,
          max:,
          min:,
          nullable:,
          optional:,
          preload:,
          sortable:,
          type:,
          writable:,
          write_only:,
          &block
        ),
      )
    end

    # @api public
    # Defines a has_one association for this representation.
    #
    # Subclasses inherit parent associations.
    #
    # @param name [Symbol]
    #   The association name.
    # @param deprecated [Boolean] (false)
    #   Whether deprecated. Metadata included in exports.
    # @param description [String, nil] (nil)
    #   The description. Metadata included in exports.
    # @param example [Object, nil] (nil)
    #   The example. Metadata included in exports.
    # @param filterable [Boolean] (false)
    #   Whether the association is filterable.
    # @param include [Symbol] (:optional) [:always, :optional]
    #   The inclusion mode.
    # @param nullable [Boolean, nil] (nil)
    #   Whether the association can be `null`.
    # @param representation [Class<Representation::Base>, nil] (nil)
    #   The representation class. If `nil`, inferred from the associated model in the same
    #   namespace (e.g., `CustomerRepresentation` for `Customer`).
    # @param sortable [Boolean] (false)
    #   Whether the association is sortable.
    # @param writable [Boolean, Symbol] (false) [:create, :update]
    #   The write access. `true` for both create and update, `:create` for create only, `:update` for update only.
    #   Requires `accepts_nested_attributes_for` on the model, where `allow_destroy: true` also enables deletion.
    # @return [void]
    #
    # @example Basic
    #   has_one :profile
    #
    # @example Explicit representation
    #   has_one :author, representation: AuthorRepresentation
    #
    # @example Always included
    #   has_one :customer, include: :always
    #
    # @example Custom association
    #   has_one :profile
    #
    #   def profile
    #     record.profile || record.build_profile
    #   end
    def has_one(
      name,
      deprecated: false,
      description: nil,
      example: nil,
      filterable: false,
      include: :optional,
      nullable: nil,
      representation: nil,
      sortable: false,
      writable: false
    )
      self.associations = associations.merge(
        name => Association.new(
          name,
          :has_one,
          self,
          deprecated:,
          description:,
          example:,
          filterable:,
          include:,
          nullable:,
          representation:,
          sortable:,
          writable:,
        ),
      )
    end

    # @api public
    # Defines a has_many association for this representation.
    #
    # Subclasses inherit parent associations.
    #
    # @param name [Symbol]
    #   The association name.
    # @param deprecated [Boolean] (false)
    #   Whether deprecated. Metadata included in exports.
    # @param description [String, nil] (nil)
    #   The description. Metadata included in exports.
    # @param example [Object, nil] (nil)
    #   The example. Metadata included in exports.
    # @param filterable [Boolean] (false)
    #   Whether the association is filterable.
    # @param include [Symbol] (:optional) [:always, :optional]
    #   The inclusion mode.
    # @param representation [Class<Representation::Base>, nil] (nil)
    #   The representation class. If `nil`, inferred from the associated model in the same
    #   namespace (e.g., `CustomerRepresentation` for `Customer`).
    # @param sortable [Boolean] (false)
    #   Whether the association is sortable.
    # @param writable [Boolean, Symbol] (false) [:create, :update]
    #   The write access. `true` for both create and update, `:create` for create only, `:update` for update only.
    #   Requires `accepts_nested_attributes_for` on the model, where `allow_destroy: true` also enables deletion.
    # @return [void]
    # @see #has_one
    #
    # @example Basic
    #   has_many :items
    #
    # @example Explicit representation
    #   has_many :comments, representation: CommentRepresentation
    #
    # @example Always included
    #   has_many :items, include: :always
    #
    # @example Custom association
    #   has_many :items
    #
    #   def items
    #     record.items.limit(5)
    #   end
    def has_many(
      name,
      deprecated: false,
      description: nil,
      example: nil,
      filterable: false,
      include: :optional,
      representation: nil,
      sortable: false,
      writable: false
    )
      self.associations = associations.merge(
        name => Association.new(
          name,
          :has_many,
          self,
          deprecated:,
          description:,
          example:,
          filterable:,
          include:,
          representation:,
          sortable:,
          writable:,
        ),
      )
    end

    # @api public
    # Defines a belongs_to association for this representation.
    #
    # Subclasses inherit parent associations.
    #
    # @param name [Symbol]
    #   The association name.
    # @param deprecated [Boolean] (false)
    #   Whether deprecated. Metadata included in exports.
    # @param description [String, nil] (nil)
    #   The description. Metadata included in exports.
    # @param example [Object, nil] (nil)
    #   The example. Metadata included in exports.
    # @param filterable [Boolean] (false)
    #   Whether the association is filterable.
    # @param include [Symbol] (:optional) [:always, :optional]
    #   The inclusion mode.
    # @param nullable [Boolean, nil] (nil)
    #   Whether the association can be `null`. If `nil`, auto-detected from foreign key column NULL constraint.
    # @param polymorphic [Array<Class<Representation::Base>>, nil] (nil)
    #   The allowed representation classes for polymorphic associations.
    # @param representation [Class<Representation::Base>, nil] (nil)
    #   The representation class. If `nil`, inferred from the associated model in the same
    #   namespace (e.g., `CustomerRepresentation` for `Customer`).
    # @param sortable [Boolean] (false)
    #   Whether the association is sortable.
    # @param writable [Boolean, Symbol] (false) [:create, :update]
    #   The write access. `true` for both create and update, `:create` for create only, `:update` for update only.
    #   Requires `accepts_nested_attributes_for` on the model, where `allow_destroy: true` also enables deletion.
    # @return [void]
    # @see #has_one
    #
    # @example Basic
    #   belongs_to :customer
    #
    # @example Explicit representation
    #   belongs_to :author, representation: AuthorRepresentation
    #
    # @example Always included
    #   belongs_to :customer, include: :always
    #
    # @example Polymorphic
    #   belongs_to :commentable, polymorphic: [PostRepresentation, CustomerRepresentation]
    #
    # @example Custom association
    #   belongs_to :customer
    #
    #   def customer
    #     record.customer || Customer.default
    #   end
    def belongs_to(
      name,
      deprecated: false,
      description: nil,
      example: nil,
      filterable: false,
      include: :optional,
      nullable: nil,
      polymorphic: nil,
      representation: nil,
      sortable: false,
      writable: false
    )
      self.associations = associations.merge(
        name => Association.new(
          name,
          :belongs_to,
          self,
          deprecated:,
          description:,
          example:,
          filterable:,
          include:,
          nullable:,
          polymorphic:,
          representation:,
          sortable:,
          writable:,
        ),
      )
    end

    # @api public
    # Defines an object type for this representation.
    #
    # The type is copied to the contract that uses this representation. Attributes can reference
    # it by name via `type:`. In exports, the type is scoped to the contract.
    #
    # @param name [Symbol]
    #   The object name.
    # @param deprecated [Boolean] (false)
    #   Whether deprecated. Metadata included in exports.
    # @param description [String, nil] (nil)
    #   The description. Metadata included in exports.
    # @param example [Object, nil] (nil)
    #   The example. Metadata included in exports.
    # @yieldparam object [API::Object]
    # @return [void]
    #
    # @example Define and reference
    #   object :address do
    #     string :street
    #     string :city
    #     string :postal_code
    #   end
    #
    #   attribute :shipping_address, type: :address
    #   attribute :billing_address, type: :address
    def object(
      name,
      deprecated: false,
      description: nil,
      example: nil,
      &block
    )
      self.type_definitions = type_definitions.merge(
        name.to_sym => {
          block:,
          kind: :object,
          options: {
            deprecated:,
            description:,
            example:,
          },
        },
      )
    end

    # @api public
    # Defines a union type for this representation.
    #
    # The type is copied to the contract that uses this representation. Attributes can reference
    # it by name via `type:`. In exports, the type is scoped to the contract.
    #
    # @param name [Symbol]
    #   The union name.
    # @param deprecated [Boolean] (false)
    #   Whether deprecated. Metadata included in exports.
    # @param description [String, nil] (nil)
    #   The description. Metadata included in exports.
    # @param discriminator [Symbol, nil] (nil)
    #   The discriminator field name.
    # @param example [Object, nil] (nil)
    #   The example. Metadata included in exports.
    # @yieldparam union [API::Union]
    # @return [void]
    #
    # @example Define and reference
    #   union :content_block, discriminator: :kind do
    #     variant tag: 'text' do
    #       object do
    #         string :body
    #       end
    #     end
    #     variant tag: 'image' do
    #       object do
    #         string :url
    #         integer :width
    #         integer :height
    #       end
    #     end
    #   end
    #
    #   attribute :content, type: :content_block
    def union(
      name,
      deprecated: false,
      description: nil,
      discriminator: nil,
      example: nil,
      &block
    )
      self.type_definitions = type_definitions.merge(
        name.to_sym => {
          block:,
          kind: :union,
          options: {
            deprecated:,
            description:,
            discriminator:,
            example:,
          },
        },
      )
    end

    # @api public
    # The type name for this representation.
    #
    # Overrides the model's default for STI and polymorphic types.
    #
    # @param value [String, Symbol, nil] (nil)
    #   The type name.
    # @return [String, nil]
    # @see .sti_name
    # @see .polymorphic_name
    #
    # @example
    #   type_name :person
    def type_name(value = nil)
      return @type_name = value.to_s if value

      @type_name
    end

    # @api public
    # The STI name for this representation.
    #
    # Uses {.type_name} if set, otherwise the model's `sti_name`.
    #
    # @return [String]
    def sti_name
      @type_name || model_class.sti_name
    end

    # @api public
    # The polymorphic name for this representation.
    #
    # Uses {.type_name} if set, otherwise the model's `polymorphic_name`.
    #
    # @return [String]
    def polymorphic_name
      @type_name || model_class.polymorphic_name
    end

    # @api public
    # Whether this representation is an STI subclass.
    #
    # @return [Boolean]
    def subclass?
      superclass.respond_to?(:inheritance) && superclass.inheritance&.subclass?(self)
    end

    # @api public
    # The description for this representation.
    #
    # Metadata included in exports.
    #
    # @param value [String, nil] (nil)
    #   The description.
    # @return [String, nil]
    #
    # @example
    #   description 'A customer invoice'
    def description(value = nil)
      return @description if value.nil?

      @description = value
    end

    # @api public
    # Marks this representation as deprecated.
    #
    # Metadata included in exports.
    #
    # @return [void]
    #
    # @example
    #   deprecated!
    def deprecated!
      @deprecated = true
    end

    # @api public
    # The example value for this representation.
    #
    # Metadata included in exports.
    #
    # @param value [Hash, nil] (nil)
    #   The example.
    # @return [Hash, nil]
    #
    # @example
    #   example id: 1, total: 99.00, status: 'paid'
    def example(value = nil)
      return @example if value.nil?

      @example = value
    end

    # @api public
    # Transforms a record or an array of records to hashes.
    #
    # Applies attribute encoders, maps STI and polymorphic type names,
    # and recursively serializes nested associations.
    #
    # @param resource [ActiveRecord::Base, Array<ActiveRecord::Base>]
    #   The resource to serialize.
    # @param context [Hash] ({})
    #   The serialization context.
    # @param include [Symbol, Array, Hash, nil] (nil)
    #   The associations to include.
    # @return [Hash, Array<Hash>]
    #
    # @example Basic
    #   InvoiceRepresentation.serialize(invoice)
    #   # => { id: 1, total: 99.00, status: 'paid' }
    #
    # @example Collection
    #   InvoiceRepresentation.serialize(invoices)
    #   # => [{ id: 1, ... }, { id: 2, ... }]
    #
    # @example With associations
    #   InvoiceRepresentation.serialize(invoice, include: [:customer, :items])
    #   # => { id: 1, ..., customer: { id: 1, name: 'Acme' }, items: [...] }
    #
    # @example Nested associations
    #   InvoiceRepresentation.serialize(invoice, include: { customer: [:address] })
    #   # => { id: 1, ..., customer: { id: 1, name: 'Acme', address: { ... } } }
    def serialize(resource, context: {}, include: nil)
      if resource.is_a?(Enumerable)
        resource.map { |record| serialize_record(record, context:, include:) }
      else
        serialize_record(resource, context:, include:)
      end
    end

    # @api public
    # Transforms a hash or an array of hashes for records.
    #
    # Applies attribute decoders, maps STI and polymorphic type names,
    # and recursively deserializes nested associations.
    #
    # @param payload [Hash, Array<Hash>]
    #   The payload to deserialize.
    # @return [Hash, Array<Hash>]
    #
    # @example
    #   InvoiceRepresentation.deserialize(params[:invoice])
    def deserialize(payload)
      Deserializer.deserialize(self, payload)
    end

    # @api public
    # The root key for this representation.
    #
    # Derived from model name when {.root} is not set.
    #
    # @return [RootKey]
    def root_key
      if @root
        RootKey.new(@root[:singular], @root[:plural])
      else
        RootKey.new(model_class.model_name.element)
      end
    end

    # @api public
    # The model class for this representation.
    #
    # Auto-detected from representation name or set via {.model}.
    #
    # @return [Class<ActiveRecord::Base>]
    def model_class
      ensure_auto_detection_complete
      ensure_sti_auto_configuration_complete
      @model_class
    end

    # @api public
    # Whether this representation is deprecated.
    #
    # @return [Boolean]
    def deprecated?
      @deprecated == true
    end

    def adapter_config
      @adapter_config ||= api_class.adapter_config.merge(_adapter_config)
    end

    def api_class
      return nil unless name

      namespace = name.deconstantize
      return nil if namespace.blank?

      API.find("/#{namespace.underscore.tr('::', '/')}")
    end

    def preloads
      attributes.values.filter_map(&:preload)
    end

    def polymorphic_association_for_type_column(column_name)
      associations.values.find do |association|
        association.polymorphic? && association.discriminator == column_name
      end
    end

    def inheritance_for_column(column_name)
      target_class = subclass? ? superclass : self
      target_inheritance = target_class.inheritance
      target_model = target_class.model_class

      return nil unless target_inheritance&.subclasses&.any?
      return nil unless target_model.respond_to?(:inheritance_column)

      target_inheritance if column_name.to_sym == target_model.inheritance_column.to_sym
    end

    def serialize_record(record, context: {}, include: nil)
      subclass_representation_class = inheritance.resolve(record) if inheritance&.subclasses&.any?
      representation_class = subclass_representation_class || self

      representation_class.new(record, context:, include:).as_json
    end

    private

    def ensure_auto_detection_complete
      return if @auto_detection_complete

      @auto_detection_complete = true
      return if @model_class.present?

      detected = ModelDetector.new(self).detect
      @model_class = detected if detected
    end

    def ensure_sti_auto_configuration_complete
      return if @sti_auto_configuration_complete

      @sti_auto_configuration_complete = true
      ensure_auto_detection_complete
      return unless @model_class

      model_detector = ModelDetector.new(self)

      auto_configure_inheritance if model_detector.sti_base?(@model_class) && inheritance.nil?

      return unless model_detector.sti_subclass?(@model_class)
      return unless model_detector.superclass_is_sti_base?(@model_class)
      return if subclass?

      auto_register_subclass
    end

    def auto_configure_inheritance
      self.inheritance = Inheritance.new(self)
    end

    def auto_register_subclass
      superclass.send(:ensure_sti_auto_configuration_complete)
      return unless superclass.inheritance

      superclass.inheritance.register(self)
      superclass._abstract = true
    end
  end

  def initialize(record, context: {}, include: nil)
    @record = record
    @context = context
    @include = include
  end

  def as_json
    Serializer.serialize(self, @include)
  end
end

.abstract? ⇒ `Boolean`

Whether this representation is abstract.

Returns:

(Boolean)

# File 'lib/apiwork/representation/base.rb', line 44

class Base
  include Abstractable

  # @!method self.attributes
  #   @api public
  #   The attributes for this representation.
  #
  #   @return [Hash{Symbol => Attribute}]
  class_attribute :attributes, default: {}, instance_accessor: false

  # @!method self.associations
  #   @api public
  #   The associations for this representation.
  #
  #   @return [Hash{Symbol => Association}]
  class_attribute :associations, default: {}, instance_accessor: false

  # @!method self.inheritance
  #   @api public
  #   The inheritance configuration for this representation.
  #
  #   Auto-configured when the model uses STI and representation classes mirror the model hierarchy.
  #   Subclasses share the parent's inheritance configuration.
  #
  #   @return [Representation::Inheritance, nil]
  class_attribute :inheritance, default: nil, instance_accessor: false

  class_attribute :_adapter_config, default: {}, instance_accessor: false
  class_attribute :type_definitions, default: {}, instance_accessor: false

  # @!attribute [r] context
  #   @api public
  #   The serialization context.
  #
  #   Passed from controller or directly to {.serialize}. Use for data that isn't on the record, like
  #   current user or permissions.
  #
  #   @return [Hash]
  #
  #   @example Override in controller
  #     def context
  #       { current_user: current_user }
  #     end
  #
  #   @example Access in custom attribute
  #     attribute :editable, type: :boolean
  #
  #     def editable
  #       context[:current_user]&.admin?
  #     end
  #
  # @!attribute [r] record
  #   @api public
  #   The record for this representation.
  #
  #   Available in custom attributes and associations.
  #
  #   @return [ActiveRecord::Base]
  #
  #   @example Custom attribute
  #     attribute :full_name, type: :string
  #
  #     def full_name
  #       "#{record.first_name} #{record.last_name}"
  #     end
  attr_reader :context,
              :record

  class << self
    # @api public
    # Configures the model class for this representation.
    #
    # Auto-detected from representation name when not set. Use {.model_class} to retrieve.
    #
    # @param value [Class<ActiveRecord::Base>]
    #   The model class.
    # @return [void]
    # @raise [ArgumentError] if value is not an ActiveRecord model class
    #
    # @example
    #   model Invoice
    def model(value)
      unless value.is_a?(Class)
        raise ConfigurationError,
              "model must be an ActiveRecord model class, got #{value.class}. " \
                                                             "Use: model Post (not 'Post' or :post)"
      end
      unless value < ActiveRecord::Base
        raise ConfigurationError,
              "model must be an ActiveRecord model class, got #{value}"
      end
      @model_class = value
    end

    # @api public
    # Configures the JSON root key for this representation.
    #
    # Auto-detected from model name when not set. Use {.root_key} to retrieve.
    #
    # @param singular [String, Symbol]
    #   The singular root key.
    # @param plural [String, Symbol] (singular.pluralize)
    #   The plural root key.
    # @return [void]
    #
    # @example
    #   root :bill, :bills
    def root(singular, plural = singular.to_s.pluralize)
      @root = { plural: plural.to_s, singular: singular.to_s }
    end

    # @api public
    # Configures adapter options for this representation.
    #
    # Overrides API-level options. Subclasses inherit parent adapter options.
    #
    # @yieldparam adapter [Configuration]
    # @return [void]
    #
    # @example
    #   adapter do
    #     pagination do
    #       strategy :cursor
    #       default_size 50
    #     end
    #   end
    def adapter(&block)
      return unless block

      self._adapter_config = _adapter_config.dup
      config = Configuration.new(api_class.adapter_class, _adapter_config)
      block.arity.positive? ? yield(config) : config.instance_eval(&block)
    end

    # @api public
    # Defines an attribute for this representation.
    #
    # Subclasses inherit parent attributes.
    #
    # @param name [Symbol]
    #   The attribute name.
    # @param decode [Proc, nil] (nil)
    #   Transform for request input (API to database). Must preserve the attribute type.
    # @param default [Object] (UNSET)
    #   The default value. Omit to declare no default. Pass `nil` for an explicit null default. If omitted and name maps to a database column, auto-detected from the column's static default.
    # @param deprecated [Boolean] (false)
    #   Whether deprecated. Metadata included in exports.
    # @param description [String, nil] (nil)
    #   The description. Metadata included in exports.
    # @param empty [Boolean, nil] (nil)
    #   Whether to use empty string instead of `null`. Serializes `nil` as `""` and deserializes `""` as `nil`. Only valid for `:string` type.
    # @param encode [Proc, nil] (nil)
    #   Transform for response output (database to API). Must preserve the attribute type.
    # @param enum [Array, nil] (nil)
    #   The allowed values. If `nil`, auto-detected from Rails enum definition.
    # @param example [Object, nil] (nil)
    #   The example. Metadata included in exports.
    # @param filterable [Boolean] (false)
    #   Whether the attribute is filterable.
    # @param format [Symbol, nil] (nil) [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :text, :url, :uuid]
    #   Format hint for exports. Does not change the type, but exports may add validation or
    #   documentation based on it. Valid formats by type: `:decimal`/`:number` (`:double`, `:float`),
    #   `:integer` (`:int32`, `:int64`), `:string` (`:date`, `:datetime`, `:email`, `:hostname`,
    #   `:ipv4`, `:ipv6`, `:password`, `:text`, `:url`, `:uuid`).
    # @param max [Integer, nil] (nil)
    #   The maximum. For `:array`: size. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.
    # @param min [Integer, nil] (nil)
    #   The minimum. For `:array`: size. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.
    # @param nullable [Boolean, nil] (nil)
    #   Whether the value can be `null`. If `nil` and name maps to a database column, auto-detected from column NULL constraint.
    # @param optional [Boolean, nil] (nil)
    #   Whether the attribute is optional for writes. If `nil` and name maps to a database column,
    #   auto-detected from column default or NULL constraint.
    # @param preload [Symbol, Array, Hash, nil] (nil)
    #   Associations to preload for this attribute. Use when custom attributes depend on associations.
    # @param sortable [Boolean] (false)
    #   Whether the attribute is sortable.
    # @param type [Symbol, nil] (nil) [:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :number, :object, :string, :time, :unknown, :uuid]
    #   The type. If `nil` and name maps to a database column, auto-detected from column type.
    #   Defaults to `:unknown` for json/jsonb columns and when no column exists (custom attributes).
    #   Use an explicit type or block in those cases.
    # @param writable [Boolean, Symbol] (false) [:create, :update]
    #   The write access. `true` for both create and update, `:create` for create only, `:update` for update only.
    # @param write_only [Boolean] (false)
    #   Whether the attribute is write-only. Write-only attributes are excluded from response
    #   serialization and response types but remain in writable payloads.
    # @yieldparam element [Representation::Element]
    # @return [void]
    #
    # @example Basic
    #   attribute :title
    #   attribute :price, type: :decimal, min: 0
    #   attribute :status, filterable: true, sortable: true
    #
    # @example Custom attribute with preload
    #   attribute :total, type: :decimal, preload: :items
    #
    #   def total
    #     record.items.sum(:amount)
    #   end
    #
    # @example Nested preload
    #   attribute :total_with_tax, type: :decimal, preload: { items: :tax_rate }
    #
    #   def total_with_tax
    #     record.items.sum { |item| item.amount * (1 + item.tax_rate.rate) }
    #   end
    #
    # @example Inline type for JSON column
    #   attribute :settings do
    #     object do
    #       string :theme
    #       boolean :notifications
    #     end
    #   end
    #
    # @example Encode/decode transforms
    #   attribute :status, encode: ->(value) { value.upcase }, decode: ->(value) { value.downcase }
    #
    # @example Writable only on create
    #   attribute :slug, writable: :create
    #
    # @example Explicit enum values
    #   attribute :priority, enum: [:low, :medium, :high]
    #
    # @example Multiple preloads
    #   attribute :summary, type: :string, preload: [:items, :customer]
    #
    #   def summary
    #     "#{record.customer.name}: #{record.items.count} items"
    #   end
    def attribute(
      name,
      decode: nil,
      default: UNSET,
      deprecated: false,
      description: nil,
      empty: nil,
      encode: nil,
      enum: nil,
      example: nil,
      filterable: false,
      format: nil,
      max: nil,
      min: nil,
      nullable: nil,
      optional: nil,
      preload: nil,
      sortable: false,
      type: nil,
      writable: false,
      write_only: false,
      &block
    )
      self.attributes = attributes.merge(
        name => Attribute.new(
          name,
          self,
          decode:,
          default:,
          deprecated:,
          description:,
          empty:,
          encode:,
          enum:,
          example:,
          filterable:,
          format:,
          max:,
          min:,
          nullable:,
          optional:,
          preload:,
          sortable:,
          type:,
          writable:,
          write_only:,
          &block
        ),
      )
    end

    # @api public
    # Defines a has_one association for this representation.
    #
    # Subclasses inherit parent associations.
    #
    # @param name [Symbol]
    #   The association name.
    # @param deprecated [Boolean] (false)
    #   Whether deprecated. Metadata included in exports.
    # @param description [String, nil] (nil)
    #   The description. Metadata included in exports.
    # @param example [Object, nil] (nil)
    #   The example. Metadata included in exports.
    # @param filterable [Boolean] (false)
    #   Whether the association is filterable.
    # @param include [Symbol] (:optional) [:always, :optional]
    #   The inclusion mode.
    # @param nullable [Boolean, nil] (nil)
    #   Whether the association can be `null`.
    # @param representation [Class<Representation::Base>, nil] (nil)
    #   The representation class. If `nil`, inferred from the associated model in the same
    #   namespace (e.g., `CustomerRepresentation` for `Customer`).
    # @param sortable [Boolean] (false)
    #   Whether the association is sortable.
    # @param writable [Boolean, Symbol] (false) [:create, :update]
    #   The write access. `true` for both create and update, `:create` for create only, `:update` for update only.
    #   Requires `accepts_nested_attributes_for` on the model, where `allow_destroy: true` also enables deletion.
    # @return [void]
    #
    # @example Basic
    #   has_one :profile
    #
    # @example Explicit representation
    #   has_one :author, representation: AuthorRepresentation
    #
    # @example Always included
    #   has_one :customer, include: :always
    #
    # @example Custom association
    #   has_one :profile
    #
    #   def profile
    #     record.profile || record.build_profile
    #   end
    def has_one(
      name,
      deprecated: false,
      description: nil,
      example: nil,
      filterable: false,
      include: :optional,
      nullable: nil,
      representation: nil,
      sortable: false,
      writable: false
    )
      self.associations = associations.merge(
        name => Association.new(
          name,
          :has_one,
          self,
          deprecated:,
          description:,
          example:,
          filterable:,
          include:,
          nullable:,
          representation:,
          sortable:,
          writable:,
        ),
      )
    end

    # @api public
    # Defines a has_many association for this representation.
    #
    # Subclasses inherit parent associations.
    #
    # @param name [Symbol]
    #   The association name.
    # @param deprecated [Boolean] (false)
    #   Whether deprecated. Metadata included in exports.
    # @param description [String, nil] (nil)
    #   The description. Metadata included in exports.
    # @param example [Object, nil] (nil)
    #   The example. Metadata included in exports.
    # @param filterable [Boolean] (false)
    #   Whether the association is filterable.
    # @param include [Symbol] (:optional) [:always, :optional]
    #   The inclusion mode.
    # @param representation [Class<Representation::Base>, nil] (nil)
    #   The representation class. If `nil`, inferred from the associated model in the same
    #   namespace (e.g., `CustomerRepresentation` for `Customer`).
    # @param sortable [Boolean] (false)
    #   Whether the association is sortable.
    # @param writable [Boolean, Symbol] (false) [:create, :update]
    #   The write access. `true` for both create and update, `:create` for create only, `:update` for update only.
    #   Requires `accepts_nested_attributes_for` on the model, where `allow_destroy: true` also enables deletion.
    # @return [void]
    # @see #has_one
    #
    # @example Basic
    #   has_many :items
    #
    # @example Explicit representation
    #   has_many :comments, representation: CommentRepresentation
    #
    # @example Always included
    #   has_many :items, include: :always
    #
    # @example Custom association
    #   has_many :items
    #
    #   def items
    #     record.items.limit(5)
    #   end
    def has_many(
      name,
      deprecated: false,
      description: nil,
      example: nil,
      filterable: false,
      include: :optional,
      representation: nil,
      sortable: false,
      writable: false
    )
      self.associations = associations.merge(
        name => Association.new(
          name,
          :has_many,
          self,
          deprecated:,
          description:,
          example:,
          filterable:,
          include:,
          representation:,
          sortable:,
          writable:,
        ),
      )
    end

    # @api public
    # Defines a belongs_to association for this representation.
    #
    # Subclasses inherit parent associations.
    #
    # @param name [Symbol]
    #   The association name.
    # @param deprecated [Boolean] (false)
    #   Whether deprecated. Metadata included in exports.
    # @param description [String, nil] (nil)
    #   The description. Metadata included in exports.
    # @param example [Object, nil] (nil)
    #   The example. Metadata included in exports.
    # @param filterable [Boolean] (false)
    #   Whether the association is filterable.
    # @param include [Symbol] (:optional) [:always, :optional]
    #   The inclusion mode.
    # @param nullable [Boolean, nil] (nil)
    #   Whether the association can be `null`. If `nil`, auto-detected from foreign key column NULL constraint.
    # @param polymorphic [Array<Class<Representation::Base>>, nil] (nil)
    #   The allowed representation classes for polymorphic associations.
    # @param representation [Class<Representation::Base>, nil] (nil)
    #   The representation class. If `nil`, inferred from the associated model in the same
    #   namespace (e.g., `CustomerRepresentation` for `Customer`).
    # @param sortable [Boolean] (false)
    #   Whether the association is sortable.
    # @param writable [Boolean, Symbol] (false) [:create, :update]
    #   The write access. `true` for both create and update, `:create` for create only, `:update` for update only.
    #   Requires `accepts_nested_attributes_for` on the model, where `allow_destroy: true` also enables deletion.
    # @return [void]
    # @see #has_one
    #
    # @example Basic
    #   belongs_to :customer
    #
    # @example Explicit representation
    #   belongs_to :author, representation: AuthorRepresentation
    #
    # @example Always included
    #   belongs_to :customer, include: :always
    #
    # @example Polymorphic
    #   belongs_to :commentable, polymorphic: [PostRepresentation, CustomerRepresentation]
    #
    # @example Custom association
    #   belongs_to :customer
    #
    #   def customer
    #     record.customer || Customer.default
    #   end
    def belongs_to(
      name,
      deprecated: false,
      description: nil,
      example: nil,
      filterable: false,
      include: :optional,
      nullable: nil,
      polymorphic: nil,
      representation: nil,
      sortable: false,
      writable: false
    )
      self.associations = associations.merge(
        name => Association.new(
          name,
          :belongs_to,
          self,
          deprecated:,
          description:,
          example:,
          filterable:,
          include:,
          nullable:,
          polymorphic:,
          representation:,
          sortable:,
          writable:,
        ),
      )
    end

    # @api public
    # Defines an object type for this representation.
    #
    # The type is copied to the contract that uses this representation. Attributes can reference
    # it by name via `type:`. In exports, the type is scoped to the contract.
    #
    # @param name [Symbol]
    #   The object name.
    # @param deprecated [Boolean] (false)
    #   Whether deprecated. Metadata included in exports.
    # @param description [String, nil] (nil)
    #   The description. Metadata included in exports.
    # @param example [Object, nil] (nil)
    #   The example. Metadata included in exports.
    # @yieldparam object [API::Object]
    # @return [void]
    #
    # @example Define and reference
    #   object :address do
    #     string :street
    #     string :city
    #     string :postal_code
    #   end
    #
    #   attribute :shipping_address, type: :address
    #   attribute :billing_address, type: :address
    def object(
      name,
      deprecated: false,
      description: nil,
      example: nil,
      &block
    )
      self.type_definitions = type_definitions.merge(
        name.to_sym => {
          block:,
          kind: :object,
          options: {
            deprecated:,
            description:,
            example:,
          },
        },
      )
    end

    # @api public
    # Defines a union type for this representation.
    #
    # The type is copied to the contract that uses this representation. Attributes can reference
    # it by name via `type:`. In exports, the type is scoped to the contract.
    #
    # @param name [Symbol]
    #   The union name.
    # @param deprecated [Boolean] (false)
    #   Whether deprecated. Metadata included in exports.
    # @param description [String, nil] (nil)
    #   The description. Metadata included in exports.
    # @param discriminator [Symbol, nil] (nil)
    #   The discriminator field name.
    # @param example [Object, nil] (nil)
    #   The example. Metadata included in exports.
    # @yieldparam union [API::Union]
    # @return [void]
    #
    # @example Define and reference
    #   union :content_block, discriminator: :kind do
    #     variant tag: 'text' do
    #       object do
    #         string :body
    #       end
    #     end
    #     variant tag: 'image' do
    #       object do
    #         string :url
    #         integer :width
    #         integer :height
    #       end
    #     end
    #   end
    #
    #   attribute :content, type: :content_block
    def union(
      name,
      deprecated: false,
      description: nil,
      discriminator: nil,
      example: nil,
      &block
    )
      self.type_definitions = type_definitions.merge(
        name.to_sym => {
          block:,
          kind: :union,
          options: {
            deprecated:,
            description:,
            discriminator:,
            example:,
          },
        },
      )
    end

    # @api public
    # The type name for this representation.
    #
    # Overrides the model's default for STI and polymorphic types.
    #
    # @param value [String, Symbol, nil] (nil)
    #   The type name.
    # @return [String, nil]
    # @see .sti_name
    # @see .polymorphic_name
    #
    # @example
    #   type_name :person
    def type_name(value = nil)
      return @type_name = value.to_s if value

      @type_name
    end

    # @api public
    # The STI name for this representation.
    #
    # Uses {.type_name} if set, otherwise the model's `sti_name`.
    #
    # @return [String]
    def sti_name
      @type_name || model_class.sti_name
    end

    # @api public
    # The polymorphic name for this representation.
    #
    # Uses {.type_name} if set, otherwise the model's `polymorphic_name`.
    #
    # @return [String]
    def polymorphic_name
      @type_name || model_class.polymorphic_name
    end

    # @api public
    # Whether this representation is an STI subclass.
    #
    # @return [Boolean]
    def subclass?
      superclass.respond_to?(:inheritance) && superclass.inheritance&.subclass?(self)
    end

    # @api public
    # The description for this representation.
    #
    # Metadata included in exports.
    #
    # @param value [String, nil] (nil)
    #   The description.
    # @return [String, nil]
    #
    # @example
    #   description 'A customer invoice'
    def description(value = nil)
      return @description if value.nil?

      @description = value
    end

    # @api public
    # Marks this representation as deprecated.
    #
    # Metadata included in exports.
    #
    # @return [void]
    #
    # @example
    #   deprecated!
    def deprecated!
      @deprecated = true
    end

    # @api public
    # The example value for this representation.
    #
    # Metadata included in exports.
    #
    # @param value [Hash, nil] (nil)
    #   The example.
    # @return [Hash, nil]
    #
    # @example
    #   example id: 1, total: 99.00, status: 'paid'
    def example(value = nil)
      return @example if value.nil?

      @example = value
    end

    # @api public
    # Transforms a record or an array of records to hashes.
    #
    # Applies attribute encoders, maps STI and polymorphic type names,
    # and recursively serializes nested associations.
    #
    # @param resource [ActiveRecord::Base, Array<ActiveRecord::Base>]
    #   The resource to serialize.
    # @param context [Hash] ({})
    #   The serialization context.
    # @param include [Symbol, Array, Hash, nil] (nil)
    #   The associations to include.
    # @return [Hash, Array<Hash>]
    #
    # @example Basic
    #   InvoiceRepresentation.serialize(invoice)
    #   # => { id: 1, total: 99.00, status: 'paid' }
    #
    # @example Collection
    #   InvoiceRepresentation.serialize(invoices)
    #   # => [{ id: 1, ... }, { id: 2, ... }]
    #
    # @example With associations
    #   InvoiceRepresentation.serialize(invoice, include: [:customer, :items])
    #   # => { id: 1, ..., customer: { id: 1, name: 'Acme' }, items: [...] }
    #
    # @example Nested associations
    #   InvoiceRepresentation.serialize(invoice, include: { customer: [:address] })
    #   # => { id: 1, ..., customer: { id: 1, name: 'Acme', address: { ... } } }
    def serialize(resource, context: {}, include: nil)
      if resource.is_a?(Enumerable)
        resource.map { |record| serialize_record(record, context:, include:) }
      else
        serialize_record(resource, context:, include:)
      end
    end

    # @api public
    # Transforms a hash or an array of hashes for records.
    #
    # Applies attribute decoders, maps STI and polymorphic type names,
    # and recursively deserializes nested associations.
    #
    # @param payload [Hash, Array<Hash>]
    #   The payload to deserialize.
    # @return [Hash, Array<Hash>]
    #
    # @example
    #   InvoiceRepresentation.deserialize(params[:invoice])
    def deserialize(payload)
      Deserializer.deserialize(self, payload)
    end

    # @api public
    # The root key for this representation.
    #
    # Derived from model name when {.root} is not set.
    #
    # @return [RootKey]
    def root_key
      if @root
        RootKey.new(@root[:singular], @root[:plural])
      else
        RootKey.new(model_class.model_name.element)
      end
    end

    # @api public
    # The model class for this representation.
    #
    # Auto-detected from representation name or set via {.model}.
    #
    # @return [Class<ActiveRecord::Base>]
    def model_class
      ensure_auto_detection_complete
      ensure_sti_auto_configuration_complete
      @model_class
    end

    # @api public
    # Whether this representation is deprecated.
    #
    # @return [Boolean]
    def deprecated?
      @deprecated == true
    end

    def adapter_config
      @adapter_config ||= api_class.adapter_config.merge(_adapter_config)
    end

    def api_class
      return nil unless name

      namespace = name.deconstantize
      return nil if namespace.blank?

      API.find("/#{namespace.underscore.tr('::', '/')}")
    end

    def preloads
      attributes.values.filter_map(&:preload)
    end

    def polymorphic_association_for_type_column(column_name)
      associations.values.find do |association|
        association.polymorphic? && association.discriminator == column_name
      end
    end

    def inheritance_for_column(column_name)
      target_class = subclass? ? superclass : self
      target_inheritance = target_class.inheritance
      target_model = target_class.model_class

      return nil unless target_inheritance&.subclasses&.any?
      return nil unless target_model.respond_to?(:inheritance_column)

      target_inheritance if column_name.to_sym == target_model.inheritance_column.to_sym
    end

    def serialize_record(record, context: {}, include: nil)
      subclass_representation_class = inheritance.resolve(record) if inheritance&.subclasses&.any?
      representation_class = subclass_representation_class || self

      representation_class.new(record, context:, include:).as_json
    end

    private

    def ensure_auto_detection_complete
      return if @auto_detection_complete

      @auto_detection_complete = true
      return if @model_class.present?

      detected = ModelDetector.new(self).detect
      @model_class = detected if detected
    end

    def ensure_sti_auto_configuration_complete
      return if @sti_auto_configuration_complete

      @sti_auto_configuration_complete = true
      ensure_auto_detection_complete
      return unless @model_class

      model_detector = ModelDetector.new(self)

      auto_configure_inheritance if model_detector.sti_base?(@model_class) && inheritance.nil?

      return unless model_detector.sti_subclass?(@model_class)
      return unless model_detector.superclass_is_sti_base?(@model_class)
      return if subclass?

      auto_register_subclass
    end

    def auto_configure_inheritance
      self.inheritance = Inheritance.new(self)
    end

    def auto_register_subclass
      superclass.send(:ensure_sti_auto_configuration_complete)
      return unless superclass.inheritance

      superclass.inheritance.register(self)
      superclass._abstract = true
    end
  end

  def initialize(record, context: {}, include: nil)
    @record = record
    @context = context
    @include = include
  end

  def as_json
    Serializer.serialize(self, @include)
  end
end

.adapter {|adapter| ... } ⇒ `void`

This method returns an undefined value.

Configures adapter options for this representation.

Overrides API-level options. Subclasses inherit parent adapter options.

Examples:

adapter do
  pagination do
    strategy :cursor
    default_size 50
  end
end

Yield Parameters:

adapter (Configuration)

# File 'lib/apiwork/representation/base.rb', line 170

def adapter(&block)
  return unless block

  self._adapter_config = _adapter_config.dup
  config = Configuration.new(api_class.adapter_class, _adapter_config)
  block.arity.positive? ? yield(config) : config.instance_eval(&block)
end

.adapter_config ⇒ `Object`



838
839
840

# File 'lib/apiwork/representation/base.rb', line 838

def adapter_config
  @adapter_config ||= api_class.adapter_config.merge(_adapter_config)
end

.api_class ⇒ `Object`

# File 'lib/apiwork/representation/base.rb', line 842

def api_class
  return nil unless name

  namespace = name.deconstantize
  return nil if namespace.blank?

  API.find("/#{namespace.underscore.tr('::', '/')}")
end

.associations ⇒ `Hash{Symbol => Association}`

The associations for this representation.

Returns:

(Hash{Symbol => Association})

59	# File 'lib/apiwork/representation/base.rb', line 59 class_attribute :associations, default: {}, instance_accessor: false

.attribute(name, decode: nil, default: UNSET, deprecated: false, description: nil, empty: nil, encode: nil, enum: nil, example: nil, filterable: false, format: nil, max: nil, min: nil, nullable: nil, optional: nil, preload: nil, sortable: false, type: nil, writable: false, write_only: false) {|element| ... } ⇒ `void`

This method returns an undefined value.

Defines an attribute for this representation.

Subclasses inherit parent attributes.

Examples:

Basic

attribute :title
attribute :price, type: :decimal, min: 0
attribute :status, filterable: true, sortable: true

Custom attribute with preload

attribute :total, type: :decimal, preload: :items

def total
  record.items.sum(:amount)
end

Nested preload

attribute :total_with_tax, type: :decimal, preload: { items: :tax_rate }

def total_with_tax
  record.items.sum { |item| item.amount * (1 + item.tax_rate.rate) }
end

Inline type for JSON column

attribute :settings do
  object do
    string :theme
    boolean :notifications
  end
end

Encode/decode transforms

attribute :status, encode: ->(value) { value.upcase }, decode: ->(value) { value.downcase }

Writable only on create

attribute :slug, writable: :create

Explicit enum values

attribute :priority, enum: [:low, :medium, :high]

Multiple preloads

attribute :summary, type: :string, preload: [:items, :customer]

def summary
  "#{record.customer.name}: #{record.items.count} items"
end

Parameters:

name (Symbol) —

The attribute name.
decode (Proc, nil) (defaults to: nil) —

(nil) Transform for request input (API to database). Must preserve the attribute type.
default (Object) (defaults to: UNSET) —

(UNSET) The default value. Omit to declare no default. Pass ‘nil` for an explicit null default. If omitted and name maps to a database column, auto-detected from the column’s static default.
deprecated (Boolean) (defaults to: false) —

(false) Whether deprecated. Metadata included in exports.
description (String, nil) (defaults to: nil) —

(nil) The description. Metadata included in exports.
empty (Boolean, nil) (defaults to: nil) —

(nil) Whether to use empty string instead of ‘null`. Serializes `nil` as `“”` and deserializes `“”` as `nil`. Only valid for `:string` type.
encode (Proc, nil) (defaults to: nil) —

(nil) Transform for response output (database to API). Must preserve the attribute type.
enum (Array, nil) (defaults to: nil) —

(nil) The allowed values. If ‘nil`, auto-detected from Rails enum definition.
example (Object, nil) (defaults to: nil) —

(nil) The example. Metadata included in exports.
filterable (Boolean) (defaults to: false) —

(false) Whether the attribute is filterable.
format (Symbol, nil) (defaults to: nil) —

(nil) [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :text, :url, :uuid] Format hint for exports. Does not change the type, but exports may add validation or documentation based on it. Valid formats by type: ‘:decimal`/`:number` (`:double`, `:float`), `:integer` (`:int32`, `:int64`), `:string` (`:date`, `:datetime`, `:email`, `:hostname`, `:ipv4`, `:ipv6`, `:password`, `:text`, `:url`, `:uuid`).
max (Integer, nil) (defaults to: nil) —

(nil) The maximum. For ‘:array`: size. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.
min (Integer, nil) (defaults to: nil) —

(nil) The minimum. For ‘:array`: size. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.
nullable (Boolean, nil) (defaults to: nil) —

(nil) Whether the value can be ‘null`. If `nil` and name maps to a database column, auto-detected from column NULL constraint.
optional (Boolean, nil) (defaults to: nil) —

(nil) Whether the attribute is optional for writes. If ‘nil` and name maps to a database column, auto-detected from column default or NULL constraint.
preload (Symbol, Array, Hash, nil) (defaults to: nil) —

(nil) Associations to preload for this attribute. Use when custom attributes depend on associations.
sortable (Boolean) (defaults to: false) —

(false) Whether the attribute is sortable.
type (Symbol, nil) (defaults to: nil) —

(nil) [:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :number, :object, :string, :time, :unknown, :uuid] The type. If ‘nil` and name maps to a database column, auto-detected from column type. Defaults to `:unknown` for json/jsonb columns and when no column exists (custom attributes). Use an explicit type or block in those cases.
writable (Boolean, Symbol) (defaults to: false) —

(false) [:create, :update] The write access. ‘true` for both create and update, `:create` for create only, `:update` for update only.
write_only (Boolean) (defaults to: false) —

(false) Whether the attribute is write-only. Write-only attributes are excluded from response serialization and response types but remain in writable payloads.

Yield Parameters:

element (Representation::Element)

# File 'lib/apiwork/representation/base.rb', line 275

def attribute(
  name,
  decode: nil,
  default: UNSET,
  deprecated: false,
  description: nil,
  empty: nil,
  encode: nil,
  enum: nil,
  example: nil,
  filterable: false,
  format: nil,
  max: nil,
  min: nil,
  nullable: nil,
  optional: nil,
  preload: nil,
  sortable: false,
  type: nil,
  writable: false,
  write_only: false,
  &block
)
  self.attributes = attributes.merge(
    name => Attribute.new(
      name,
      self,
      decode:,
      default:,
      deprecated:,
      description:,
      empty:,
      encode:,
      enum:,
      example:,
      filterable:,
      format:,
      max:,
      min:,
      nullable:,
      optional:,
      preload:,
      sortable:,
      type:,
      writable:,
      write_only:,
      &block
    ),
  )
end

.attributes ⇒ `Hash{Symbol => Attribute}`

The attributes for this representation.

Returns:

(Hash{Symbol => Attribute})

52	# File 'lib/apiwork/representation/base.rb', line 52 class_attribute :attributes, default: {}, instance_accessor: false

.belongs_to(name, deprecated: false, description: nil, example: nil, filterable: false, include: :optional, nullable: nil, polymorphic: nil, representation: nil, sortable: false, writable: false) ⇒ `void`

This method returns an undefined value.

Defines a belongs_to association for this representation.

Subclasses inherit parent associations.

Examples:

Basic

belongs_to :customer

Explicit representation

belongs_to :author, representation: AuthorRepresentation

Always included

belongs_to :customer, include: :always

Polymorphic

belongs_to :commentable, polymorphic: [PostRepresentation, CustomerRepresentation]

Custom association

belongs_to :customer

def customer
  record.customer || Customer.default
end

Parameters:

name (Symbol) —

The association name.
deprecated (Boolean) (defaults to: false) —

(false) Whether deprecated. Metadata included in exports.
description (String, nil) (defaults to: nil) —

(nil) The description. Metadata included in exports.
example (Object, nil) (defaults to: nil) —

(nil) The example. Metadata included in exports.
filterable (Boolean) (defaults to: false) —

(false) Whether the association is filterable.
include (Symbol) (defaults to: :optional) —

(:optional) [:always, :optional] The inclusion mode.
nullable (Boolean, nil) (defaults to: nil) —

(nil) Whether the association can be ‘null`. If `nil`, auto-detected from foreign key column NULL constraint.
polymorphic (Array<Class<Representation::Base>>, nil) (defaults to: nil) —

(nil) The allowed representation classes for polymorphic associations.
representation (Class<Representation::Base>, nil) (defaults to: nil) —

(nil) The representation class. If ‘nil`, inferred from the associated model in the same namespace (e.g., `CustomerRepresentation` for `Customer`).
sortable (Boolean) (defaults to: false) —

(false) Whether the association is sortable.
writable (Boolean, Symbol) (defaults to: false) —

(false) [:create, :update] The write access. ‘true` for both create and update, `:create` for create only, `:update` for update only. Requires `accepts_nested_attributes_for` on the model, where `allow_destroy: true` also enables deletion.

.deprecated! ⇒ `void`

This method returns an undefined value.

Marks this representation as deprecated.

Metadata included in exports.

Examples:

deprecated!



730
731
732

# File 'lib/apiwork/representation/base.rb', line 730

def deprecated!
  @deprecated = true
end

.deprecated? ⇒ `Boolean`

Whether this representation is deprecated.

Returns:

(Boolean)



834
835
836

# File 'lib/apiwork/representation/base.rb', line 834

def deprecated?
  @deprecated == true
end

.description(value = nil) ⇒ `String`^?

The description for this representation.

Metadata included in exports.

Examples:

description 'A customer invoice'

Parameters:

value (String, nil) (defaults to: nil) —

(nil) The description.

Returns:

(String, nil)

# File 'lib/apiwork/representation/base.rb', line 715

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

  @description = value
end

.deserialize(payload) ⇒ `Hash`⁺

Transforms a hash or an array of hashes for records.

Applies attribute decoders, maps STI and polymorphic type names, and recursively deserializes nested associations.

Examples:

InvoiceRepresentation.deserialize(params[:invoice])

Parameters:

payload (Hash, Array<Hash>) —

The payload to deserialize.

Returns:

(Hash, Array<Hash>)



800
801
802

# File 'lib/apiwork/representation/base.rb', line 800

def deserialize(payload)
  Deserializer.deserialize(self, payload)
end

.example(value = nil) ⇒ `Hash`^?

The example value for this representation.

Metadata included in exports.

Examples:

example id: 1, total: 99.00, status: 'paid'

Parameters:

value (Hash, nil) (defaults to: nil) —

(nil) The example.

Returns:

(Hash, nil)

# File 'lib/apiwork/representation/base.rb', line 745

def example(value = nil)
  return @example if value.nil?

  @example = value
end

.has_many(name, deprecated: false, description: nil, example: nil, filterable: false, include: :optional, representation: nil, sortable: false, writable: false) ⇒ `void`

This method returns an undefined value.

Defines a has_many association for this representation.

Subclasses inherit parent associations.

Examples:

Basic

has_many :items

Explicit representation

has_many :comments, representation: CommentRepresentation

Always included

has_many :items, include: :always

Custom association

has_many :items

def items
  record.items.limit(5)
end

Parameters:

name (Symbol) —

The association name.
deprecated (Boolean) (defaults to: false) —

(false) Whether deprecated. Metadata included in exports.
description (String, nil) (defaults to: nil) —

(nil) The description. Metadata included in exports.
example (Object, nil) (defaults to: nil) —

(nil) The example. Metadata included in exports.
filterable (Boolean) (defaults to: false) —

(false) Whether the association is filterable.
include (Symbol) (defaults to: :optional) —

(:optional) [:always, :optional] The inclusion mode.
representation (Class<Representation::Base>, nil) (defaults to: nil) —

(nil) The representation class. If ‘nil`, inferred from the associated model in the same namespace (e.g., `CustomerRepresentation` for `Customer`).
sortable (Boolean) (defaults to: false) —

(false) Whether the association is sortable.
writable (Boolean, Symbol) (defaults to: false) —

(false) [:create, :update] The write access. ‘true` for both create and update, `:create` for create only, `:update` for update only. Requires `accepts_nested_attributes_for` on the model, where `allow_destroy: true` also enables deletion.

.has_one(name, deprecated: false, description: nil, example: nil, filterable: false, include: :optional, nullable: nil, representation: nil, sortable: false, writable: false) ⇒ `void`

This method returns an undefined value.

Defines a has_one association for this representation.

Subclasses inherit parent associations.

Examples:

Basic

has_one :profile

Explicit representation

has_one :author, representation: AuthorRepresentation

Always included

has_one :customer, include: :always

Custom association

has_one :profile

def profile
  record.profile || record.build_profile
end

Parameters:

name (Symbol) —

The association name.
deprecated (Boolean) (defaults to: false) —

(false) Whether deprecated. Metadata included in exports.
description (String, nil) (defaults to: nil) —

(nil) The description. Metadata included in exports.
example (Object, nil) (defaults to: nil) —

(nil) The example. Metadata included in exports.
filterable (Boolean) (defaults to: false) —

(false) Whether the association is filterable.
include (Symbol) (defaults to: :optional) —

(:optional) [:always, :optional] The inclusion mode.
nullable (Boolean, nil) (defaults to: nil) —

(nil) Whether the association can be ‘null`.
representation (Class<Representation::Base>, nil) (defaults to: nil) —

(nil) The representation class. If ‘nil`, inferred from the associated model in the same namespace (e.g., `CustomerRepresentation` for `Customer`).
sortable (Boolean) (defaults to: false) —

(false) Whether the association is sortable.
writable (Boolean, Symbol) (defaults to: false) —

(false) [:create, :update] The write access. ‘true` for both create and update, `:create` for create only, `:update` for update only. Requires `accepts_nested_attributes_for` on the model, where `allow_destroy: true` also enables deletion.

# File 'lib/apiwork/representation/base.rb', line 370

def has_one(
  name,
  deprecated: false,
  description: nil,
  example: nil,
  filterable: false,
  include: :optional,
  nullable: nil,
  representation: nil,
  sortable: false,
  writable: false
)
  self.associations = associations.merge(
    name => Association.new(
      name,
      :has_one,
      self,
      deprecated:,
      description:,
      example:,
      filterable:,
      include:,
      nullable:,
      representation:,
      sortable:,
      writable:,
    ),
  )
end

.inheritance ⇒ `Representation::Inheritance`^?

The inheritance configuration for this representation.

Auto-configured when the model uses STI and representation classes mirror the model hierarchy. Subclasses share the parent’s inheritance configuration.

Returns:

(Representation::Inheritance, nil)

69	# File 'lib/apiwork/representation/base.rb', line 69 class_attribute :inheritance, default: nil, instance_accessor: false

.inheritance_for_column(column_name) ⇒ `Object`

# File 'lib/apiwork/representation/base.rb', line 861

def inheritance_for_column(column_name)
  target_class = subclass? ? superclass : self
  target_inheritance = target_class.inheritance
  target_model = target_class.model_class

  return nil unless target_inheritance&.subclasses&.any?
  return nil unless target_model.respond_to?(:inheritance_column)

  target_inheritance if column_name.to_sym == target_model.inheritance_column.to_sym
end

.model(value) ⇒ `void`

This method returns an undefined value.

Configures the model class for this representation.

Auto-detected from representation name when not set. Use model_class to retrieve.

Examples:

model Invoice

Parameters:

value (Class<ActiveRecord::Base>) —

The model class.

Raises:

(ArgumentError) —

if value is not an ActiveRecord model class

# File 'lib/apiwork/representation/base.rb', line 125

def model(value)
  unless value.is_a?(Class)
    raise ConfigurationError,
          "model must be an ActiveRecord model class, got #{value.class}. " \
                                                         "Use: model Post (not 'Post' or :post)"
  end
  unless value < ActiveRecord::Base
    raise ConfigurationError,
          "model must be an ActiveRecord model class, got #{value}"
  end
  @model_class = value
end

.model_class ⇒ `Class<ActiveRecord::Base>`

The model class for this representation.

Auto-detected from representation name or set via model.

Returns:

(Class<ActiveRecord::Base>)

# File 'lib/apiwork/representation/base.rb', line 824

def model_class
  ensure_auto_detection_complete
  ensure_sti_auto_configuration_complete
  @model_class
end

.object(name, deprecated: false, description: nil, example: nil) {|object| ... } ⇒ `void`

This method returns an undefined value.

Defines an object type for this representation.

The type is copied to the contract that uses this representation. Attributes can reference it by name via ‘type:`. In exports, the type is scoped to the contract.

Examples:

Define and reference

object :address do
  string :street
  string :city
  string :postal_code
end

attribute :shipping_address, type: :address
attribute :billing_address, type: :address

Parameters:

name (Symbol) —

The object name.
deprecated (Boolean) (defaults to: false) —

(false) Whether deprecated. Metadata included in exports.
description (String, nil) (defaults to: nil) —

(nil) The description. Metadata included in exports.
example (Object, nil) (defaults to: nil) —

(nil) The example. Metadata included in exports.

Yield Parameters:

object (API::Object)

# File 'lib/apiwork/representation/base.rb', line 579

def object(
  name,
  deprecated: false,
  description: nil,
  example: nil,
  &block
)
  self.type_definitions = type_definitions.merge(
    name.to_sym => {
      block:,
      kind: :object,
      options: {
        deprecated:,
        description:,
        example:,
      },
    },
  )
end

.polymorphic_association_for_type_column(column_name) ⇒ `Object`

# File 'lib/apiwork/representation/base.rb', line 855

def polymorphic_association_for_type_column(column_name)
  associations.values.find do |association|
    association.polymorphic? && association.discriminator == column_name
  end
end

.polymorphic_name ⇒ `String`

The polymorphic name for this representation.

Uses type_name if set, otherwise the model’s ‘polymorphic_name`.

Returns:

(String)



692
693
694

# File 'lib/apiwork/representation/base.rb', line 692

def polymorphic_name
  @type_name || model_class.polymorphic_name
end

.preloads ⇒ `Object`



851
852
853

# File 'lib/apiwork/representation/base.rb', line 851

def preloads
  attributes.values.filter_map(&:preload)
end

.root(singular, plural = singular.to_s.pluralize) ⇒ `void`

This method returns an undefined value.

Configures the JSON root key for this representation.

Auto-detected from model name when not set. Use root_key to retrieve.

Examples:

root :bill, :bills

Parameters:

singular (String, Symbol) —

The singular root key.
plural (String, Symbol) (defaults to: singular.to_s.pluralize) —

(singular.pluralize) The plural root key.



151
152
153

# File 'lib/apiwork/representation/base.rb', line 151

def root(singular, plural = singular.to_s.pluralize)
  @root = { plural: plural.to_s, singular: singular.to_s }
end

.root_key ⇒ `RootKey`

The root key for this representation.

Derived from model name when root is not set.

Returns:

(RootKey)

# File 'lib/apiwork/representation/base.rb', line 810

def root_key
  if @root
    RootKey.new(@root[:singular], @root[:plural])
  else
    RootKey.new(model_class.model_name.element)
  end
end

.serialize(resource, context: {}, include: nil) ⇒ `Hash`⁺

Transforms a record or an array of records to hashes.

Applies attribute encoders, maps STI and polymorphic type names, and recursively serializes nested associations.

Examples:

Basic

InvoiceRepresentation.serialize(invoice)
# => { id: 1, total: 99.00, status: 'paid' }

Collection

InvoiceRepresentation.serialize(invoices)
# => [{ id: 1, ... }, { id: 2, ... }]

With associations

InvoiceRepresentation.serialize(invoice, include: [:customer, :items])
# => { id: 1, ..., customer: { id: 1, name: 'Acme' }, items: [...] }

Nested associations

InvoiceRepresentation.serialize(invoice, include: { customer: [:address] })
# => { id: 1, ..., customer: { id: 1, name: 'Acme', address: { ... } } }

Parameters:

resource (ActiveRecord::Base, Array<ActiveRecord::Base>) —

The resource to serialize.
context (Hash) (defaults to: {}) —

({}) The serialization context.
include (Symbol, Array, Hash, nil) (defaults to: nil) —

(nil) The associations to include.

Returns:

(Hash, Array<Hash>)

# File 'lib/apiwork/representation/base.rb', line 780

def serialize(resource, context: {}, include: nil)
  if resource.is_a?(Enumerable)
    resource.map { |record| serialize_record(record, context:, include:) }
  else
    serialize_record(resource, context:, include:)
  end
end

.serialize_record(record, context: {}, include: nil) ⇒ `Object`

# File 'lib/apiwork/representation/base.rb', line 872

def serialize_record(record, context: {}, include: nil)
  subclass_representation_class = inheritance.resolve(record) if inheritance&.subclasses&.any?
  representation_class = subclass_representation_class || self

  representation_class.new(record, context:, include:).as_json
end

.sti_name ⇒ `String`

The STI name for this representation.

Uses type_name if set, otherwise the model’s ‘sti_name`.

Returns:

(String)



682
683
684

# File 'lib/apiwork/representation/base.rb', line 682

def sti_name
  @type_name || model_class.sti_name
end

.subclass? ⇒ `Boolean`

Whether this representation is an STI subclass.

Returns:

(Boolean)



700
701
702

# File 'lib/apiwork/representation/base.rb', line 700

def subclass?
  superclass.respond_to?(:inheritance) && superclass.inheritance&.subclass?(self)
end

.type_name(value = nil) ⇒ `String`^?

The type name for this representation.

Overrides the model’s default for STI and polymorphic types.

Examples:

type_name :person

Parameters:

value (String, Symbol, nil) (defaults to: nil) —

(nil) The type name.

Returns:

(String, nil)

.union(name, deprecated: false, description: nil, discriminator: nil, example: nil) {|union| ... } ⇒ `void`

This method returns an undefined value.

Defines a union type for this representation.

The type is copied to the contract that uses this representation. Attributes can reference it by name via ‘type:`. In exports, the type is scoped to the contract.

Examples:

Define and reference

union :content_block, discriminator: :kind do
  variant tag: 'text' do
    object do
      string :body
    end
  end
  variant tag: 'image' do
    object do
      string :url
      integer :width
      integer :height
    end
  end
end

attribute :content, type: :content_block

Parameters:

name (Symbol) —

The union name.
deprecated (Boolean) (defaults to: false) —

(false) Whether deprecated. Metadata included in exports.
description (String, nil) (defaults to: nil) —

(nil) The description. Metadata included in exports.
discriminator (Symbol, nil) (defaults to: nil) —

(nil) The discriminator field name.
example (Object, nil) (defaults to: nil) —

(nil) The example. Metadata included in exports.

Yield Parameters:

union (API::Union)

# File 'lib/apiwork/representation/base.rb', line 635

def union(
  name,
  deprecated: false,
  description: nil,
  discriminator: nil,
  example: nil,
  &block
)
  self.type_definitions = type_definitions.merge(
    name.to_sym => {
      block:,
      kind: :union,
      options: {
        deprecated:,
        description:,
        discriminator:,
        example:,
      },
    },
  )
end

Instance Method Details

#as_json ⇒ `Object`



928
929
930

# File 'lib/apiwork/representation/base.rb', line 928

def as_json
  Serializer.serialize(self, @include)
end

Class: Apiwork::Representation::Base

Overview

Examples:

Basic representation

Contract

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(record, context: {}, include: nil) ⇒ Base

Instance Attribute Details

#context ⇒ Hash (readonly)

Examples:

Override in controller

Access in custom attribute

#record ⇒ Object (readonly)

Class Method Details

.abstract! ⇒ void

Examples:

Application base representation

.abstract? ⇒ Boolean

.adapter {|adapter| ... } ⇒ void

Examples:

.adapter_config ⇒ Object

.api_class ⇒ Object

.associations ⇒ Hash{Symbol => Association}

Examples:

Basic

Custom attribute with preload

Nested preload

Inline type for JSON column

Encode/decode transforms

Writable only on create

Explicit enum values

Multiple preloads

.attributes ⇒ Hash{Symbol => Attribute}

.belongs_to(name, deprecated: false, description: nil, example: nil, filterable: false, include: :optional, nullable: nil, polymorphic: nil, representation: nil, sortable: false, writable: false) ⇒ void

Examples:

Basic

Explicit representation

Always included

Polymorphic

Custom association

.deprecated! ⇒ void

Examples:

.deprecated? ⇒ Boolean

.description(value = nil) ⇒ String?

Examples:

.deserialize(payload) ⇒ Hash+

Examples:

.example(value = nil) ⇒ Hash?

Examples:

.has_many(name, deprecated: false, description: nil, example: nil, filterable: false, include: :optional, representation: nil, sortable: false, writable: false) ⇒ void

Examples:

Basic

Explicit representation

Always included

Custom association

.has_one(name, deprecated: false, description: nil, example: nil, filterable: false, include: :optional, nullable: nil, representation: nil, sortable: false, writable: false) ⇒ void

Examples:

Basic

Explicit representation

Always included

Custom association

.inheritance ⇒ Representation::Inheritance?

.inheritance_for_column(column_name) ⇒ Object

.model(value) ⇒ void

Examples:

.model_class ⇒ Class<ActiveRecord::Base>

.object(name, deprecated: false, description: nil, example: nil) {|object| ... } ⇒ void

Examples:

Define and reference

.polymorphic_association_for_type_column(column_name) ⇒ Object

.polymorphic_name ⇒ String

.preloads ⇒ Object

.root(singular, plural = singular.to_s.pluralize) ⇒ void

Examples:

.root_key ⇒ RootKey

.serialize(resource, context: {}, include: nil) ⇒ Hash+

Examples:

#initialize(record, context: {}, include: nil) ⇒ `Base`

#context ⇒ `Hash` (readonly)

#record ⇒ `Object` (readonly)

.abstract! ⇒ `void`

.abstract? ⇒ `Boolean`

.adapter {|adapter| ... } ⇒ `void`

.adapter_config ⇒ `Object`

.api_class ⇒ `Object`

.associations ⇒ `Hash{Symbol => Association}`

.attributes ⇒ `Hash{Symbol => Attribute}`

.belongs_to(name, deprecated: false, description: nil, example: nil, filterable: false, include: :optional, nullable: nil, polymorphic: nil, representation: nil, sortable: false, writable: false) ⇒ `void`

.deprecated! ⇒ `void`

.deprecated? ⇒ `Boolean`

.description(value = nil) ⇒ `String`^?

.deserialize(payload) ⇒ `Hash`⁺

.example(value = nil) ⇒ `Hash`^?

.has_many(name, deprecated: false, description: nil, example: nil, filterable: false, include: :optional, representation: nil, sortable: false, writable: false) ⇒ `void`

.has_one(name, deprecated: false, description: nil, example: nil, filterable: false, include: :optional, nullable: nil, representation: nil, sortable: false, writable: false) ⇒ `void`

.inheritance ⇒ `Representation::Inheritance`^?

.inheritance_for_column(column_name) ⇒ `Object`

.model(value) ⇒ `void`

.model_class ⇒ `Class<ActiveRecord::Base>`

.object(name, deprecated: false, description: nil, example: nil) {|object| ... } ⇒ `void`

.polymorphic_association_for_type_column(column_name) ⇒ `Object`

.polymorphic_name ⇒ `String`

.preloads ⇒ `Object`

.root(singular, plural = singular.to_s.pluralize) ⇒ `void`

.root_key ⇒ `RootKey`

.serialize(resource, context: {}, include: nil) ⇒ `Hash`⁺

.serialize_record(record, context: {}, include: nil) ⇒ `Object`

.sti_name ⇒ `String`

.subclass? ⇒ `Boolean`

.type_name(value = nil) ⇒ `String`^?

.union(name, deprecated: false, description: nil, discriminator: nil, example: nil) {|union| ... } ⇒ `void`

#as_json ⇒ `Object`