class SoberSwag::Serializer::Base

Base class for everything that provides serialization functionality in SoberSwag. SoberSwag serializers transform Ruby types into JSON types, with some associated schema. This schema is then used in the generated OpenAPI V3 documentation.

Public Instance Methods

array() click to toggle source

Return a new serializer that is an array of elements of this serializer. This serializer will take in an array, and use `self` to serialize every element.

@return [SoberSwag::Serializer::Array]

# File lib/sober_swag/serializer/base.rb, line 13
def array
  SoberSwag::Serializer::Array.new(self)
end
finalize_lazy_type!() click to toggle source

Finalize a lazy type.

Should be idempotent: call it once, and it does nothing on subsequent calls (but returns the type).

# File lib/sober_swag/serializer/base.rb, line 97
def finalize_lazy_type!
  type
end
identifier(arg = nil) click to toggle source

@overload identifier()

Returns the external identifier, used to uniquely identify this object within
the schemas section of an OpenAPI v3 document.
@return [String] the identifier.

@overload identifier(arg)

Sets the external identifier to use to uniquely identify
this object within the schemas section of an OpenAPI v3 document.
@param arg [String] the identifier to use
@return [String] the identifer set
# File lib/sober_swag/serializer/base.rb, line 133
def identifier(arg = nil)
  @identifier = arg if arg
  @identifier
end
lazy_type() click to toggle source

The lazy version of this type, for mutual recursion. @see lazy_type? for why this is needed

Once you call {#finalize_lazy_type!}, the type will be “fleshed out,” and can be actually used.

# File lib/sober_swag/serializer/base.rb, line 89
def lazy_type
  type
end
lazy_type?() click to toggle source

Is this type lazily defined?

If we have two serializers that are *mutually recursive*, we need to do some “fun” magic to make that work. This comes up in a case like:

“`ruby

SchoolClass = SoberSwag::OutputObject.define do
  field :name, primitive(:String)
  view :detail do
    field :students, -> { Student.view(:base) }
  end
end

Student = SoberSwag::OutputObject.define do
  field :name, primitive(:String)
  view :detail do
    field :classes, -> { SchoolClass.view(:base) }
  end
end

“`

This would result in an infinite loop if we tried to define the type struct the easy way. So, we instead use mutation to achieve “laziness.”

# File lib/sober_swag/serializer/base.rb, line 80
def lazy_type?
  false
end
meta(hash) click to toggle source

Add metadata onto the type of a serializer. Note that this *returns a new serializer with metadata added* and does not perform mutation. @param hash [Hash] the metadata to set. @return [SoberSwag::Serializer::Meta] a serializer with metadata added

# File lib/sober_swag/serializer/base.rb, line 32
def meta(hash)
  SoberSwag::Serializer::Meta.new(self, hash)
end
nilable()
Alias for: optional
optional() click to toggle source

Returns a serializer that will pass `nil` values on unscathed. That means that if you try to serialize `nil` with it, it will result in a JSON `null`. @return [SoberSwag::Serializer::Optional]

# File lib/sober_swag/serializer/base.rb, line 21
def optional
  SoberSwag::Serializer::Optional.new(self)
end
Also aliased as: nilable
serialize(_object, _options = {}) click to toggle source

Serialize an object. @abstract

# File lib/sober_swag/serializer/base.rb, line 104
def serialize(_object, _options = {})
  raise ArgumentError, 'not implemented!'
end
serializer() click to toggle source

Returns self.

This exists due to a hack.

# File lib/sober_swag/serializer/base.rb, line 119
def serializer
  self
end
type() click to toggle source

Get the type that we serialize to. @abstract

# File lib/sober_swag/serializer/base.rb, line 111
def type
  raise ArgumentError, 'not implemented!'
end
via_map(&block) click to toggle source

Get a new serializer that will first run the given block before serializing an object. For example, if you have a serializer for strings called `StringSerializer`, and you want to serialize `Date` objects via encoding them to a standardized string format, you can use:

“`

DateSerializer = StringSerializer.via_map do |date|
  date.strftime('%Y-%m-%d')
end

“`

@yieldparam [Object] the object before serialization @yieldreturn [Object] a transformed object, that will

be passed to {#serialize}

@return [SoberSwag::Serializer::Mapped] the new serializer

# File lib/sober_swag/serializer/base.rb, line 52
def via_map(&block)
  SoberSwag::Serializer::Mapped.new(self, block)
end