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
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 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
@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
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
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
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
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
Serialize an object. @abstract
# File lib/sober_swag/serializer/base.rb, line 104 def serialize(_object, _options = {}) raise ArgumentError, 'not implemented!' end
Returns self.
This exists due to a hack.
# File lib/sober_swag/serializer/base.rb, line 119 def serializer self end
Get the type that we serialize to. @abstract
# File lib/sober_swag/serializer/base.rb, line 111 def type raise ArgumentError, 'not implemented!' end
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