sober_swag 0.1.0 → 0.2.0

data/lib/sober_swag/controller/route.rb

@@ -1,9 +1,8 @@
-require 'sober_swag/blueprint'
-
 module SoberSwag
   module Controller
+    ##
+    # Describe a single controller endpoint.
     class Route
-
       def initialize(method, action_name, path)
         @method = method
         @path = path
@@ -12,12 +11,8 @@ module SoberSwag
         @response_descriptions = {}
       end
 
-      attr_reader :response_serializers
-      attr_reader :response_descriptions
-      attr_reader :controller
-      attr_reader :method
-      attr_reader :path
-      attr_reader :action_name
+      attr_reader :response_serializers, :response_descriptions, :controller, :method, :path, :action_name
+
       ##
       # What to parse the request body in to.
       attr_reader :request_body_class
@@ -31,10 +26,10 @@ module SoberSwag
 
       ##
       # Define the request body, using SoberSwag's type-definition scheme.
-      # The block passed will be used to define the body of a new sublcass of `base` (defaulted to {Dry::Struct}.)
+      # The block passed will be used to define the body of a new sublcass of `base` (defaulted to {SoberSwag::InputObject}.)
       # If you want, you can also define utility methods in here
-      def request_body(base = Dry::Struct, &block)
-        @request_body_class = make_struct!(base, &block)
+      def request_body(base = SoberSwag::InputObject, &block)
+        @request_body_class = make_input_object!(base, &block)
         action_module.const_set('ResponseBody', @request_body_class)
       end
 
@@ -48,8 +43,8 @@ module SoberSwag
       # Define the shape of the query_params parameters, using SoberSwag's type-definition scheme.
       # The block passed is the body of the newly-defined type.
       # You can also include a base type.
-      def query_params(base = Dry::Struct, &block)
-        @query_params_class = make_struct!(base, &block)
+      def query_params(base = SoberSwag::InputObject, &block)
+        @query_params_class = make_input_object!(base, &block)
         action_module.const_set('QueryParams', @query_params_class)
       end
 
@@ -61,10 +56,10 @@ module SoberSwag
 
       ##
       # Define the shape of the *path* parameters, using SoberSwag's type-definition scheme.
-      # The block passed will be the body of a new subclass of `base` (defaulted to {Dry::Struct}).
+      # The block passed will be the body of a new subclass of `base` (defaulted to {SoberSwag::InputObject}).
       # Names of this should match the names in the path template originally passed to {SoberSwag::Controller::Route.new}
-      def path_params(base = Dry::Struct, &block)
-        @path_params_class = make_struct!(base, &block)
+      def path_params(base = SoberSwag::InputObject, &block)
+        @path_params_class = make_input_object!(base, &block)
         action_module.const_set('PathParams', @path_params_class)
       end
 
@@ -104,13 +99,13 @@ module SoberSwag
       ##
       # Define a serializer for a response with the given status code.
       # You may either give a serializer you defined elsewhere, or define one inline as if passed to
-      # {SoberSwag::Blueprint.define}
+      # {SoberSwag::OutputObject.define}
       def response(status_code, description, serializer = nil, &block)
         status_key = Rack::Utils.status_code(status_code)
 
         raise ArgumentError, 'Response defiend!' if @response_serializers.key?(status_key)
 
-        serializer ||= SoberSwag::Blueprint.define(&block)
+        serializer ||= SoberSwag::OutputObject.define(&block)
         response_module.const_set(status_code.to_s.classify, serializer)
         @response_serializers[status_key] = serializer
         @response_descriptions[status_key] = description
@@ -128,8 +123,10 @@ module SoberSwag
         @response_module ||= Module.new.tap { |m| action_module.const_set(:Response, m) }
       end
 
-      def make_struct!(base, &block)
-        Class.new(base, &block).tap { |e| e.transform_keys(&:to_sym) if base == Dry::Struct }
+      def make_input_object!(base, &block)
+        Class.new(base, &block).tap do |e|
+          e.transform_keys(&:to_sym) if [SoberSwag::InputObject, Dry::Struct].include?(base)
+        end
       end
     end
   end

data/lib/sober_swag/controller/undefined_body_error.rb

@@ -1,5 +1,8 @@
 module SoberSwag
   module Controller
+    ##
+    # Error class thrown if you have no body defined,
+    # but try to call `parsed_body`.
     class UndefinedBodyError < Error
     end
   end

data/lib/sober_swag/controller/undefined_path_error.rb

@@ -1,5 +1,8 @@
 module SoberSwag
   module Controller
+    ##
+    # Error class thrown if you have no path defined,
+    # but try to call `parse_path`.
     class UndefinedPathError < Error
     end
   end

data/lib/sober_swag/controller/undefined_query_error.rb

@@ -1,5 +1,8 @@
 module SoberSwag
   module Controller
+    ##
+    # Error class thrown if you have no query defined,
+    # but try to call `parsed_query`.
     class UndefinedQueryError < Error
     end
   end

data/lib/sober_swag/input_object.rb

@@ -0,0 +1,28 @@
+module SoberSwag
+  ##
+  # A variant of Dry::Struct that allows you to set a "model name" that is publically visible.
+  # If you do not set one, it will be the Ruby class name, with any '::' replaced with a '.'.
+  #
+  # This otherwise behaves exactly like a Dry::Struct.
+  # Please see the documentation for that class to see how it works.
+  class InputObject < Dry::Struct
+    transform_keys(&:to_sym)
+
+    class << self
+      ##
+      # The name to use for this type in external documentation.
+      def identifier(arg = nil)
+        @identifier = arg if arg
+        @identifier || name.to_s.gsub('::', '.')
+      end
+
+      def primitive(sym)
+        SoberSwag::Types.const_get(sym)
+      end
+
+      def param(sym)
+        SoberSwag::Types::Params.const_get(sym)
+      end
+    end
+  end
+end

data/lib/sober_swag/nodes/array.rb

@@ -22,7 +22,7 @@ module SoberSwag
         @elements
       end
 
-      def deconstruct_keys(keys)
+      def deconstruct_keys(_keys)
         { elements: @elements }
       end
     end

data/lib/sober_swag/nodes/base.rb

@@ -9,7 +9,6 @@ module SoberSwag
     # - #deconstruct_keys, which returns a hash of *everything needed to identify the node*.
     #   We use this later.
     class Base
-
       include Comparable
 
       ##
@@ -38,14 +37,13 @@ module SoberSwag
       #
       # When working with these definition nodes, we very often want to transform something recursively.
       # This method allows us to do so by focusing on a single level at a time, keeping the actual recursion *abstract*.
-      def cata(&block)
+      def cata
         raise ArgumentError, 'Base is abstract'
       end
 
-      def map(&block)
+      def map
         raise ArgumentError, 'Base is abstract'
       end
-
     end
   end
 end

data/lib/sober_swag/nodes/binary.rb

@@ -11,6 +11,7 @@ module SoberSwag
       end
 
       attr_reader :lhs, :rhs
+
       ##
       # Map the root values of the node.
       # This just calls map on the lhs and the rhs
@@ -25,7 +26,7 @@ module SoberSwag
         [lhs, rhs]
       end
 
-      def deconstruct_keys(keys)
+      def deconstruct_keys(_keys)
         { lhs: lhs, rhs: rhs }
       end
 

data/lib/sober_swag/nodes/enum.rb

@@ -1,7 +1,9 @@
 module SoberSwag
   module Nodes
+    ##
+    # Compiler node to represent an enum value.
+    # Enums are special enough to have their own node.
     class Enum < Base
-
       def initialize(values)
         @values = values
       end
@@ -16,7 +18,7 @@ module SoberSwag
         [values]
       end
 
-      def deconstruct_keys(keys)
+      def deconstruct_keys(_keys)
         { values: values }
       end
 

data/lib/sober_swag/nodes/list.rb

@@ -34,7 +34,6 @@ module SoberSwag
           element.map(&block)
         )
       end
-
     end
   end
 end

data/lib/sober_swag/nodes/primitive.rb

@@ -3,26 +3,27 @@ module SoberSwag
     ##
     # Root node of the tree
     class Primitive < Base
-      def initialize(value)
+      def initialize(value, metadata = {})
         @value = value
+        @metadata = metadata
       end
 
-      attr_reader :value
+      attr_reader :value, :metadata
 
       def map(&block)
         self.class.new(block.call(value))
       end
 
       def deconstruct
-        [value]
+        [value, metadata]
       end
 
       def deconstruct_keys(_)
-        { value: value }
+        { value: value, metadata: metadata }
       end
 
       def cata(&block)
-        block.call(self.class.new(value))
+        block.call(self.class.new(value, metadata))
       end
     end
   end

data/lib/sober_swag/output_object.rb

@@ -0,0 +1,102 @@
+require 'sober_swag/serializer'
+
+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}.
+  class OutputObject < SoberSwag::Serializer::Base
+    autoload(:Field, 'sober_swag/output_object/field')
+    autoload(:Definition, 'sober_swag/output_object/definition')
+    autoload(:FieldSyntax, 'sober_swag/output_object/field_syntax')
+    autoload(:View, 'sober_swag/output_object/view')
+
+    ##
+    # Use a OutputObject to define a new serializer.
+    # It will be based on {SoberSwag::Serializer::Base}.
+    #
+    # An example is illustrative:
+    #
+    #     PersonSerializer = SoberSwag::OutputObject.define do
+    #       field :id, primitive(:Integer)
+    #       field :name, primtive(:String).optional
+    #
+    #       view :complex do
+    #         field :age, primitive(:Integer)
+    #         field :title, primitive(:String)
+    #       end
+    #     end
+    #
+    # Note: This currently will generate a new *class* that does serialization.
+    # 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}
+    # can simply return an *instance* of SoberSwag::Serializer that does
+    # the correct thing, with the name you give it. This works for now, though.
+    def self.define(&block)
+      d = Definition.new.tap do |o|
+        o.instance_eval(&block)
+      end
+      new(d.fields, d.views, d.identifier)
+    end
+
+    def initialize(fields, views, identifier)
+      @fields = fields
+      @views = views
+      @identifier = identifier
+    end
+
+    attr_reader :fields, :views, :identifier
+
+    def serialize(obj, opts = {})
+      serializer.serialize(obj, opts)
+    end
+
+    def type
+      serializer.type
+    end
+
+    def view(name)
+      return base_serializer if name == :base
+
+      @views.find { |v| v.name == name }
+    end
+
+    def base
+      base_serializer
+    end
+
+    ##
+    # 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
+      @serializer ||=
+        begin
+          views.reduce(base_serializer) do |base, view|
+            view_serializer = view.serializer
+            view_serializer.identifier("#{identifier}.#{view.name.to_s.classify}") if identifier
+            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
+        end
+    end
+
+    def base_serializer
+      @base_serializer ||= SoberSwag::Serializer::FieldList.new(fields).tap do |s|
+        s.identifier(identifier)
+      end
+    end
+  end
+end

data/lib/sober_swag/output_object/definition.rb

@@ -0,0 +1,30 @@
+module SoberSwag
+  class OutputObject
+    ##
+    # Container to define a single output object.
+    # This is the DSL used in the base of {SoberSwag::OutputObject.define}.
+    class Definition
+      def initialize
+        @fields = []
+        @views = []
+      end
+
+      attr_reader :fields, :views
+
+      include FieldSyntax
+
+      def add_field!(field)
+        @fields << field
+      end
+
+      def view(name, &block)
+        @views << View.define(name, fields, &block)
+      end
+
+      def identifier(arg = nil)
+        @identifier = arg if arg
+        @identifier
+      end
+    end
+  end
+end

data/lib/sober_swag/{blueprint → output_object}/field.rb

@@ -1,5 +1,8 @@
 module SoberSwag
-  class Blueprint
+  class OutputObject
+    ##
+    # A single field in an output object.
+    # Later used to make an actual serializer from this.
     class Field
       def initialize(name, serializer, from: nil, &block)
         @name = name
@@ -11,12 +14,20 @@ module SoberSwag
       attr_reader :name
 
       def serializer
-        @serializer ||= @root_serializer.serializer.via_map(&transform_proc)
+        @serializer ||= resolved_serializer.serializer.via_map(&transform_proc)
+      end
+
+      def resolved_serializer
+        if @root_serializer.is_a?(Proc)
+          @root_serializer.call
+        else
+          @root_serializer
+        end
       end
 
       private
 
-      def transform_proc
+      def transform_proc # rubocop:disable Metrics/MethodLength
         if @block
           @block
         else
@@ -30,7 +41,6 @@ module SoberSwag
           end
         end
       end
-
     end
   end
 end

data/lib/sober_swag/{blueprint → output_object}/field_syntax.rb

@@ -1,5 +1,5 @@
 module SoberSwag
-  class Blueprint
+  class OutputObject
     ##
     # Syntax for definitions that can add fields.
     module FieldSyntax