sober_swag 0.19.0 → 0.23.0

data/lib/sober_swag/output_object/view.rb

@@ -3,44 +3,87 @@ module SoberSwag
     ##
     # DSL for defining a view.
     # Used in `view` blocks within {SoberSwag::OutputObject.define}.
+    #
+    # Views are "variants" of {SoberSwag::OutputObject}s that contain
+    # different fields.
     class View < SoberSwag::Serializer::Base
+      ##
+      # Define a new view with the given base fields.
+      # @param name [Symbol] name for this view
+      # @param base_fields [Array<SoberSwag::OutputObject::Field>] fields already defined
+      # @yieldself [SoberSwag::OutputObject::View]
+      #
+      # @return [SoberSwag::OutputObject::View]
       def self.define(name, base_fields, &block)
         new(name, base_fields).tap do |view|
           view.instance_eval(&block)
         end
       end
 
+      ##
+      # An error thrown when you try to nest views inside views.
       class NestingError < Error; end
 
       include FieldSyntax
 
+      ##
+      # @param name [Sybmol] name for this view.
+      # @param base_fields [Array<SoberSwag::OutputObject::Field>] already-defined fields.
       def initialize(name, base_fields = [])
         @name = name
         @fields = base_fields.dup
       end
 
-      attr_reader :name, :fields
+      ##
+      # @return [Symbol] the name of this view
+      attr_reader :name
+
+      ##
+      # @return [Array<SoberSwag::OutputObject::Fields>] the fields defined in this view.
+      attr_reader :fields
 
+      ##
+      # Serialize an object according to this view.
+      # @param object what to serialize
+      # @param opts [Hash] arbitrary options
+      # @return [Hash] the serialized result
       def serialize(obj, opts = {})
         serializer.serialize(obj, opts)
       end
 
+      ##
+      # Get the type of this view.
+      # @return [Class] the type, a subclass of {Dry::Struct}
       def type
         serializer.type
       end
 
+      ##
+      # Excludes a field with the given name from this view.
+      # @param name [Symbol] field to exclude.
+      # @return [nil] nothing interesting
       def except!(name)
         @fields.reject! { |f| f.name == name }
       end
 
+      ##
+      # Always raises {NestingError}
+      # @raise {NestingError} always
       def view(*)
         raise NestingError, 'no views in views'
       end
 
+      ##
+      # Adds a field do this view.
+      # @param field [SoberSwag::OutputObject::Field]
+      # @return [nil] nothing interesting
       def add_field!(field)
         @fields << field
       end
 
+      ##
+      # Pretty show for humans
+      # @return [String]
       def to_s
         "<SoberSwag::OutputObject::View(#{identifier})>"
       end
@@ -48,6 +91,8 @@ module SoberSwag
       ##
       # Get the serializer defined by this view.
       # WARNING: Don't add more fields after you call this.
+      #
+      # @return [SoberSwag::Serializer::FieldList]
       def serializer
         @serializer ||=
           SoberSwag::Serializer::FieldList.new(fields).tap { |s| s.identifier(identifier) }

data/lib/sober_swag/output_object.rb

@@ -5,7 +5,7 @@ module SoberSwag
   # Create a serializer that is heavily inspired by the "Blueprinter" library.
   # This allows you to make "views" and such inside.
   #
-  # Under the hood, this is actually all based on {SoberSwag::Serialzier::Base}.
+  # Under the hood, this is actually all based on {SoberSwag::Serializer::Base}.
   class OutputObject < SoberSwag::Serializer::Base
     autoload(:Field, 'sober_swag/output_object/field')
     autoload(:Definition, 'sober_swag/output_object/definition')
@@ -20,7 +20,7 @@ module SoberSwag
     #
     #     PersonSerializer = SoberSwag::OutputObject.define do
     #       field :id, primitive(:Integer)
-    #       field :name, primtive(:String).optional
+    #       field :name, primitive(:String).optional
     #
     #       view :complex do
     #         field :age, primitive(:Integer)
@@ -32,9 +32,12 @@ module SoberSwag
     # However, this is only a hack to get rid of the weird naming issue when
     # generating swagger from dry structs: their section of the schema area
     # is defined by their *Ruby Class Name*. In the future, if we get rid of this,
-    # we might be able to keep this on the value-level, in which case {#define}
+    # we might be able to keep this on the value-level, in which case {.define}
     # can simply return an *instance* of SoberSwag::Serializer that does
     # the correct thing, with the name you give it. This works for now, though.
+    #
+    # @return [Class] the serializer generated.
+    # @yieldself [SoberSwag::OutputObject::Definition]
     def self.define(&block)
       d = Definition.new.tap do |o|
         o.instance_eval(&block)
@@ -42,28 +45,51 @@ module SoberSwag
       new(d.fields, d.views, d.identifier)
     end
 
+    ##
+    # @param fields [Array<SoberSwag::OutputObject::Field>] the fields for this OutputObject
+    # @param views [Array<SoberSwag::OutputObject::View>] the views for this OutputObject
+    # @param identifier [String] the external identifier for this OutputObject
     def initialize(fields, views, identifier)
       @fields = fields
       @views = views
       @identifier = identifier
     end
 
-    attr_reader :fields, :views, :identifier
+    ##
+    # @return [Array<SoberSwag::OutputObject::Field>]
+    attr_reader :fields
+    ##
+    # @return [Array<SoberSwag::OutputObject::View>]
+    attr_reader :views
+    ##
+    # @return [String] the external ID to use for this object
+    attr_reader :identifier
 
+    ##
+    # Perform serialization.
     def serialize(obj, opts = {})
       serializer.serialize(obj, opts)
     end
 
+    ##
+    # Get a Dry::Struct of the type this OutputObject will serialize to.
     def type
       serializer.type
     end
 
+    ##
+    # Get a serializer for a single view contained in this output object.
+    # Note: given `:base`, it will return a serializer for the base OutputObject
+    # @param name [Symbol] the name of the view
+    # @return [SoberSwag::Serializer::Base] the serializer
     def view(name)
       return base_serializer if name == :base
 
       @views.find { |v| v.name == name }
     end
 
+    ##
+    # A serializer for the "base type" of this OutputObject, with no views.
     def base
       base_serializer
     end
@@ -72,30 +98,25 @@ module SoberSwag
     # Compile down this to an appropriate serializer.
     # It uses {SoberSwag::Serializer::Conditional} to do view-parsing,
     # and {SoberSwag::Serializer::FieldList} to do the actual serialization.
-    def serializer # rubocop:disable Metrics/MethodLength
+    #
+    # @todo: optimize view selection to use binary instead of linear search
+    def serializer
       @serializer ||=
         begin
-          views.reduce(base_serializer) do |base, view|
-            view_serializer = view.serializer
-            SoberSwag::Serializer::Conditional.new(
-              proc do |object, options|
-                if options[:view].to_s == view.name.to_s
-                  [:left, object]
-                else
-                  [:right, object]
-                end
-              end,
-              view_serializer,
-              base
-            )
-          end
+          view_choices = views.map { |view| [view.name.to_s, view.serializer] }.to_h
+          view_choices['base'] = base_serializer
+          SoberSwag::Serializer::Hash.new(view_choices, base, proc { |_, options| options[:view]&.to_s })
         end
     end
 
+    ##
+    # @return [String]
     def to_s
       "<SoberSwag::OutputObject(#{identifier})>"
     end
 
+    ##
+    # @return [SoberSwag::Serializer::FieldList] serializer for this output object.
     def base_serializer
       @base_serializer ||= SoberSwag::Serializer::FieldList.new(fields).tap do |s|
         s.identifier(identifier)

data/lib/sober_swag/parser.rb

@@ -1,13 +1,19 @@
 module SoberSwag
   ##
   # Parses a *Dry-Types Schema* into a set of nodes we can use to compile.
-  # This is mostly because the vistior pattern sucks and catamorphisms are nice.
+  # This is mostly because the visitor pattern sucks and catamorphisms are nice.
+  #
+  # Do not use this class directly, as it is not part of the public api.
+  # Instead, use classes from the {SoberSwag::Compiler} namespace.
   class Parser
     def initialize(node)
       @node = node
       @found = Set.new
     end
 
+    ##
+    # Compile to one of our internal nodes.
+    # @return [SoberSwag::Nodes::Base] the node that describes this type.
     def to_syntax # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
       case @node
       when Dry::Types::Default

data/lib/sober_swag/reporting/compiler.rb

@@ -0,0 +1,39 @@
+module SoberSwag
+  module Reporting
+    module Compiler
+      ##
+      # Compile component schemas.
+      class Schema
+        def initialize
+          @references = {}
+          @referenced_schemas = Set.new
+        end
+
+        ##
+        # Hash of references to type definitions.
+        # Suitable for us as the components hash.
+        attr_reader :references
+
+        def compile(value)
+          compile_inner(value.swagger_schema)
+        end
+
+        def compile_inner(value)
+          initial, found = value
+
+          merge_found(found)
+
+          initial
+        end
+
+        def merge_found(found)
+          found.each do |k, v|
+            next unless @referenced_schemas.add?(k)
+
+            @references[k] = compile_inner(v.call)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/base.rb

@@ -0,0 +1,11 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Base class for all inputs in the cool new schema style.
+      class Base
+        include Interface
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/bool.rb

@@ -0,0 +1,19 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Convert booleans.
+      class Bool < Base
+        def call(val)
+          return Report::Value.new(['was not a bool']) unless [true, false].include?(val)
+
+          val
+        end
+
+        def swagger_schema
+          [{ type: 'boolean' }, {}]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/converting/bool.rb

@@ -0,0 +1,24 @@
+module SoberSwag
+  module Reporting
+    module Input
+      module Converting
+        ##
+        # Try to convert a boolean-like value to an actual boolean.
+        Bool = # rubocop:disable Naming/ConstantName
+          (SoberSwag::Reporting::Input::Bool.new |
+           (
+             SoberSwag::Reporting::Input::Text
+              .new
+              .enum(*(%w[y yes true t].flat_map { |x| [x, x.upcase] } + ['1'])) |
+              SoberSwag::Reporting::Input::Number.new.enum(1)).mapped { |_| true } |
+            (
+              SoberSwag::Reporting::Input::Text
+                .new
+                .enum(*(%w[false no n f].flat_map { |x| [x, x.upcase] } + ['0'])) |
+              SoberSwag::Reporting::Input::Number.new.enum(0)
+            ).mapped { |_| false }
+          )
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/converting/date.rb

@@ -0,0 +1,30 @@
+module SoberSwag
+  module Reporting
+    module Input
+      module Converting
+        ##
+        # Convert via a date.
+        #
+        # Note: unlike the swagger spec, we first try to convert
+        # rfc8601, then try rfc3339.
+        Date = (
+          SoberSwag::Reporting::Input::Text
+               .new
+               .mapped { |str|
+            begin
+              ::Date.rfc3339(str)
+            rescue ArgumentError
+              Report::Value.new(['was not an RFC 3339 date string'])
+            end
+          } |
+          SoberSwag::Reporting::Input::Text
+            .new
+            .mapped do |str|
+            ::Date.iso8601(str)
+          rescue ArgumentError
+            Report::Value.new(['was not an ISO8601 date string'])
+          end).format('date')
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/converting/date_time.rb

@@ -0,0 +1,28 @@
+module SoberSwag
+  module Reporting
+    module Input
+      module Converting
+        ##
+        # Convert via a date.
+        DateTime =
+          SoberSwag::Reporting::Input::Text
+          .new
+          .mapped { |str|
+            begin
+              ::DateTime.rfc3339(str)
+            rescue ArgumentError
+              Report::Value.new(['was not an RFC 3339 date-time string'])
+            end
+          }.or(
+            SoberSwag::Reporting::Input::Text
+              .new
+              .mapped do |str|
+              ::DateTime.iso8601(str)
+            rescue ArgumentError
+              Report::Value.new(['was not an ISO8601 date-time string'])
+            end
+          ).format('date-time')
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/converting/decimal.rb

@@ -0,0 +1,24 @@
+module SoberSwag
+  module Reporting
+    module Input
+      module Converting
+        ##
+        # Parse a decimal.
+        Decimal =
+          (SoberSwag::Reporting::Input::Number.new.mapped(&:to_d).format(:decimal) |
+          SoberSwag::Reporting::Input::Text
+          .new
+          .format('decimal')
+          .mapped do |v|
+            BigDecimal(v)
+          rescue ArgumentError
+            Report::Value.new('was not a decimal')
+          end).described(<<~MARKDOWN).referenced('SoberSwag.Converting.Decimal')
+            Decimal formatted input.
+            Will either convert a JSON number to a decimal, or accept a string representation.
+            The string representation allows for greater precision.
+          MARKDOWN
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/converting/integer.rb

@@ -0,0 +1,19 @@
+module SoberSwag
+  module Reporting
+    module Input
+      module Converting
+        Integer =
+          (SoberSwag::Reporting::Input.number.format('integer').mapped(&:to_i)) |
+          (SoberSwag::Reporting::Input.text.format('integer').mapped do |v|
+            Integer(v)
+          rescue ArgumentError
+            Report::Value.new(['was not an integer string'])
+          end).described(<<~MARKDOWN).referenced('SoberSwag.Converting.Integer')
+            Integer formatted input.
+
+            With either convert a JSON number to an integer, or accept a string representation of an integer.
+          MARKDOWN
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/converting.rb

@@ -0,0 +1,16 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Namespace for things that can do conversion.
+      # These are really just compound types that kinda look nice.
+      module Converting
+        autoload(:Decimal, 'sober_swag/reporting/input/converting/decimal')
+        autoload(:Date, 'sober_swag/reporting/input/converting/date')
+        autoload(:DateTime, 'sober_swag/reporting/input/converting/date_time')
+        autoload(:Bool, 'sober_swag/reporting/input/converting/bool')
+        autoload(:Integer, 'sober_swag/reporting/input/converting/integer')
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/defer.rb

@@ -0,0 +1,29 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Resolve circular references by deferring the loading of an input.
+      class Defer < Base
+        def initialize(other_lazy)
+          @other_lazy = other_lazy
+        end
+
+        attr_reader :other_lazy
+
+        def other
+          return @other if defined?(@other)
+
+          @other = other_lazy.call
+        end
+
+        def call(input)
+          other.call(input)
+        end
+
+        def swagger_schema
+          other.swagger_schema
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/described.rb

@@ -0,0 +1,38 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Node for things with descriptions.
+      # This describes the *type*, not the *object key*.
+      class Described < Base
+        def initialize(input, description)
+          @input = input
+          @description = description
+        end
+
+        ##
+        # @return [Interface] base input
+        attr_reader :input
+
+        ##
+        # @return [String] description of input
+        attr_reader :description
+
+        def call(value)
+          input.call(value)
+        end
+
+        def swagger_schema
+          val, other = input.swagger_schema
+          merged =
+            if val.key?(:$ref)
+              { allOf: [val] }
+            else
+              val
+            end.merge(description: description)
+          [merged, other]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/dictionary.rb

@@ -0,0 +1,37 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Dictionary types: string keys, something else as a value.
+      class Dictionary < Base
+        def self.of(input_type)
+          new(input_type)
+        end
+
+        def initialize(value_input)
+          @value_input = value_input
+        end
+
+        attr_reader :value_input
+
+        def call(value)
+          return Report::Base.new(['was not an object']) unless value.is_a?(Hash)
+
+          bad, good = value.map { |k, v|
+            [k, value_input.call(v)]
+          }.compact.partition { |(_, v)| v.is_a?(Report::Base) }
+
+          return Report::Object.new(bad.to_h) if bad.any?
+
+          good.to_h
+        end
+
+        def swagger_schema
+          schema, found = value_input.swagger_schema
+
+          [{ type: :object, additionalProperties: schema }, found]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/either.rb

@@ -0,0 +1,51 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Parses either one input, or another.
+      # Left-biased.
+      class Either < Base
+        ##
+        # @param lhs [Base] an input we will try first
+        # @param rhs [Base] an input we will try second
+        def initialize(lhs, rhs)
+          @lhs = lhs
+          @rhs = rhs
+        end
+
+        ##
+        # @return [Base] parser for LHS
+        attr_reader :lhs
+        ##
+        # @return [Base] parser for RHS
+        attr_reader :rhs
+
+        def call(value)
+          maybe_lhs = lhs.call(value)
+
+          return maybe_lhs unless maybe_lhs.is_a?(Report::Base)
+
+          maybe_rhs = rhs.call(value)
+
+          return maybe_rhs unless maybe_rhs.is_a?(Report::Base)
+
+          Report::Either.new(maybe_lhs, maybe_rhs)
+        end
+
+        def swagger_schema
+          lhs_val, lhs_set = lhs.swagger_schema
+          rhs_val, rhs_set = rhs.swagger_schema
+
+          val = { oneOf: defs_for(lhs_val) + defs_for(rhs_val) }
+          [val, lhs_set.merge(rhs_set)]
+        end
+
+        private
+
+        def defs_for(schema)
+          schema[:oneOf] || [schema]
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/input/enum.rb

@@ -0,0 +1,44 @@
+module SoberSwag
+  module Reporting
+    module Input
+      ##
+      # Specify that a value must be included in a list of possible values.
+      class Enum < Base
+        def initialize(input, values)
+          @input = input
+          @values = values
+        end
+
+        ##
+        # @return [Interface] base type
+        attr_reader :input
+
+        ##
+        # @return [Array<String>] acceptable types
+        attr_reader :values
+
+        def call(value)
+          inner = input.call(value)
+
+          return inner if inner.is_a?(Report::Base)
+
+          return Report::Value.new(['was not an acceptable enum member']) unless values.include?(inner)
+
+          inner
+        end
+
+        def swagger_schema
+          schema, found = input.swagger_schema
+
+          merged =
+            if schema.key?(:$ref)
+              { allOf: [schema] }
+            else
+              schema
+            end.merge(enum: values)
+          [merged, found]
+        end
+      end
+    end
+  end
+end