Class: SoberSwag::Serializer::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/sober_swag/serializer/base.rb

Overview

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.

Instance Method Summary collapse

Instance Method Details

#array ⇒ SoberSwag::Serializer::Array

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.

Returns:



13
14
15
 
# File 'lib/sober_swag/serializer/base.rb', line 13

def array
  SoberSwag::Serializer::Array.new(self)
end

#finalize_lazy_type! ⇒ Object

Finalize a lazy type.

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



97
98
99
 
# File 'lib/sober_swag/serializer/base.rb', line 97

def finalize_lazy_type!
  type
end

#identifier ⇒ String #identifier(arg) ⇒ String

Overloads:

  • #identifier ⇒ String

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

    Returns:

    • (String) —

      the identifier.

  • #identifier(arg) ⇒ String

    Sets the external identifier to use to uniquely identify this object within the schemas section of an OpenAPI v3 document.

    Parameters:

    • arg (String) —

      the identifier to use

    Returns:

    • (String) —

      the identifer set



133
134
135
136
 
# File 'lib/sober_swag/serializer/base.rb', line 133

def identifier(arg = nil)
  @identifier = arg if arg
  @identifier
end

#lazy_type ⇒ Object

The lazy version of this type, for mutual recursion. Once you call #finalize_lazy_type!, the type will be "fleshed out," and can be actually used.

See Also:



89
90
91
 
# File 'lib/sober_swag/serializer/base.rb', line 89

def lazy_type
  type
end

#lazy_type? ⇒ Boolean

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:

  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."

Returns:

  • (Boolean) 


80
81
82
 
# File 'lib/sober_swag/serializer/base.rb', line 80

def lazy_type?
  false
end

#meta(hash) ⇒ SoberSwag::Serializer::Meta

Add metadata onto the type of a serializer. Note that this returns a new serializer with metadata added and does not perform mutation.

Parameters:

  • hash (Hash) —

    the metadata to set.

Returns:



32
33
34
 
# File 'lib/sober_swag/serializer/base.rb', line 32

def meta(hash)
  SoberSwag::Serializer::Meta.new(self, hash)
end

#optional ⇒ SoberSwag::Serializer::Optional Also known as: nilable

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.

Returns:



21
22
23
 
# File 'lib/sober_swag/serializer/base.rb', line 21

def optional
  SoberSwag::Serializer::Optional.new(self)
end

#serialize(_object, _options = {}) ⇒ Object

This method is abstract.

Serialize an object.

Raises:

  • (ArgumentError) 


104
105
106
 
# File 'lib/sober_swag/serializer/base.rb', line 104

def serialize(_object, _options = {})
  raise ArgumentError, 'not implemented!'
end

#serializer ⇒ Object

Returns self.

This exists due to a hack.



119
120
121
 
# File 'lib/sober_swag/serializer/base.rb', line 119

def serializer
  self
end

#type ⇒ Object

This method is abstract.

Get the type that we serialize to.

Raises:

  • (ArgumentError) 


111
112
113
 
# File 'lib/sober_swag/serializer/base.rb', line 111

def type
  raise ArgumentError, 'not implemented!'
end

#via_map {|the| ... } ⇒ SoberSwag::Serializer::Mapped

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

Yield Parameters:

  • the (Object) —

    object before serialization

Yield Returns:

  • (Object) —

    a transformed object, that will be passed to #serialize

Returns:



52
53
54
 
# File 'lib/sober_swag/serializer/base.rb', line 52

def via_map(&block)
  SoberSwag::Serializer::Mapped.new(self, block)
end