sober_swag 0.1.0 → 0.6.0

data/lib/sober_swag/controller.rb

@@ -10,10 +10,19 @@ module SoberSwag
     autoload :UndefinedPathError, 'sober_swag/controller/undefined_path_error'
     autoload :UndefinedQueryError, 'sober_swag/controller/undefined_query_error'
 
+    ##
+    # Types module, so you can more easily access Types::Whatever
+    # without having to type SoberSwag::Types::Whatever.
     module Types
       include ::Dry::Types()
     end
 
+    included do
+      rescue_from Dry::Struct::Error do
+        head :bad_request
+      end
+    end
+
     class_methods do
       ##
       # Define a new action with the given HTTP method, action name, and path.
@@ -65,10 +74,7 @@ module SoberSwag
             res = defined_routes.reduce(SoberSwag::Compiler.new) { |c, r| c.add_route(r) }
             {
               openapi: '3.0.0',
-              info: {
-                version: '1',
-                title: self.name
-              }
+              info: { version: '1', title: name }
             }.merge(res.to_swagger)
           end
       end
@@ -89,6 +95,7 @@ module SoberSwag
         begin
           r = current_action_def
           raise UndefinedPathError unless r&.path_params_class
+
           r.path_params_class.new(request.path_parameters)
         end
     end
@@ -102,6 +109,7 @@ module SoberSwag
         begin
           r = current_action_def
           raise UndefinedBodyError unless r&.request_body_class
+
           r.request_body_class.new(body_params)
         end
     end
@@ -115,6 +123,7 @@ module SoberSwag
         begin
           r = current_action_def
           raise UndefinedQueryError unless r&.query_params_class
+
           r.query_params_class.new(request.query_parameters)
         end
     end
@@ -124,11 +133,11 @@ module SoberSwag
     # @todo figure out how to specify views and other options for the serializer here
     # @param status [Symbol] the HTTP status symbol to use for the status code
     # @param entity the thing to serialize
-    def respond!(status, entity)
+    def respond!(status, entity, serializer_opts: {}, rails_opts: {})
       r = current_action_def
       serializer = r.response_serializers[Rack::Utils.status_code(status)]
       serializer ||= serializer.new if serializer.respond_to?(:new)
-      render json: serializer.serialize(entity)
+      render json: serializer.serialize(entity, serializer_opts), status: status, **rails_opts
     end
 
     ##
@@ -138,10 +147,7 @@ module SoberSwag
     # but it keeps the docs honest: parameters sent in the body *must* be
     # in the body.
     def body_params
-      bparams = params.reject do |k, _|
-        request.query_parameters.key?(k) || request.path_parameters.key?(k)
-      end
-      bparams.permit(bparams.keys)
+      request.request_parameters
     end
 
     ##
@@ -150,7 +156,6 @@ module SoberSwag
     def current_action_def
       self.class.find_route(params[:action])
     end
-
   end
 end
 

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,17 @@ 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
 
+      def flatten_one_ofs
+        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