sober_swag 0.1.0

data/example/person.json

@@ -0,0 +1,4 @@
+{
+  "first_name": "Tony",
+  "last_name": "Super"
+}

data/example/public/robots.txt

@@ -0,0 +1 @@
+# See https://www.robotstxt.org/robotstxt.html for documentation on how to use the robots.txt file

data/example/test/fixtures/people.yml

@@ -0,0 +1,11 @@
+# Read about fixtures at https://api.rubyonrails.org/classes/ActiveRecord/FixtureSet.html
+
+one:
+  first_name: MyText
+  last_name: MyText
+  date_of_birth: 2020-03-11 09:20:21
+
+two:
+  first_name: MyText
+  last_name: MyText
+  date_of_birth: 2020-03-11 09:20:21

data/example/test/models/person_test.rb

@@ -0,0 +1,7 @@
+require 'test_helper'
+
+class PersonTest < ActiveSupport::TestCase
+  # test "the truth" do
+  #   assert true
+  # end
+end

data/example/test/test_helper.rb

@@ -0,0 +1,13 @@
+ENV['RAILS_ENV'] ||= 'test'
+require_relative '../config/environment'
+require 'rails/test_help'
+
+class ActiveSupport::TestCase
+  # Run tests in parallel with specified workers
+  parallelize(workers: :number_of_processors)
+
+  # Setup all fixtures in test/fixtures/*.yml for all tests in alphabetical order.
+  fixtures :all
+
+  # Add more helper methods to be used by all tests here...
+end

data/lib/sober_swag/blueprint/field.rb

@@ -0,0 +1,36 @@
+module SoberSwag
+  class Blueprint
+    class Field
+      def initialize(name, serializer, from: nil, &block)
+        @name = name
+        @root_serializer = serializer
+        @from = from
+        @block = block
+      end
+
+      attr_reader :name
+
+      def serializer
+        @serializer ||= @root_serializer.serializer.via_map(&transform_proc)
+      end
+
+      private
+
+      def transform_proc
+        if @block
+          @block
+        else
+          key = @from || @name
+          proc do |object, _|
+            if object.respond_to?(key)
+              object.public_send(key)
+            else
+              object[key]
+            end
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/sober_swag/blueprint/field_syntax.rb

@@ -0,0 +1,17 @@
+module SoberSwag
+  class Blueprint
+    ##
+    # Syntax for definitions that can add fields.
+    module FieldSyntax
+      def field(name, serializer, from: nil, &block)
+        add_field!(Field.new(name, serializer, from: from, &block))
+      end
+
+      ##
+      # Given a symbol to this, we will use a primitive name
+      def primitive(name)
+        SoberSwag::Serializer.Primitive(SoberSwag::Types.const_get(name))
+      end
+    end
+  end
+end

data/lib/sober_swag/blueprint/view.rb

@@ -0,0 +1,44 @@
+module SoberSwag
+  class Blueprint
+    class View
+
+      def self.define(name, base_fields, &block)
+        self.new(name, base_fields).tap do |view|
+          view.instance_eval(&block)
+        end
+      end
+
+      class NestingError < Error; end;
+
+      include FieldSyntax
+
+      def initialize(name, base_fields = [])
+        @name = name
+        @fields = base_fields.dup
+      end
+
+      attr_reader :name, :fields
+
+      def except!(name)
+        @fields.select! { |f| f.name != name }
+      end
+
+      def view(*)
+        raise NestingError, 'no views in views'
+      end
+
+      def add_field!(field)
+        @fields << field
+      end
+
+      ##
+      # Get the serializer defined by this view.
+      # WARNING: Don't add more fields after you call this.
+      def serializer
+        @serializer ||=
+          SoberSwag::Serializer::FieldList.new(fields)
+      end
+
+    end
+  end
+end

data/lib/sober_swag/blueprint.rb

@@ -0,0 +1,113 @@
+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 Blueprint
+    autoload(:Field, 'sober_swag/blueprint/field')
+    autoload(:FieldSyntax, 'sober_swag/blueprint/field_syntax')
+    autoload(:View, 'sober_swag/blueprint/view')
+
+    ##
+    # Use a Blueprint to define a new serializer.
+    # It will be based on {SoberSwag::Serializer::Base}.
+    #
+    # An example is illustrative:
+    #
+    #     PersonSerializer = SoberSwag::Blueprint.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)
+      self.new.tap { |o|
+        o.instance_eval(&block)
+      }.serializer_class
+    end
+
+    def initialize(base_fields = [])
+      @fields = base_fields.dup
+      @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
+
+    ##
+    # Instead of generating a new value-level construct,
+    # this will generate a new *class*. This is so that you can
+    # name this blueprint, and have the views named as sub-classes.
+    # This is important as the type compiler uses class names
+    # for generating refs.
+    def serializer_class
+      @serializer_class ||= make_serializer_class!
+    end
+
+    private
+
+    def make_serializer_class!
+      # Klass we'll use
+      klass = Class.new(SoberSwag::Serializer::Base)
+      # The actual serialization logic is defined in a field list
+      base_serializer = SoberSwag::Serializer::FieldList.new(fields)
+      # WhateverBlueprint::Base is now used as the name for a ref
+      klass.const_set(:Base, base_serializer.type)
+      final_serializer = views.reduce(base_serializer) do |base, view|
+        view_serializer = view.serializer
+        # If we have a view :foo, its type is named
+        # WhateverBlueprint::Foo
+        klass.const_set(view.name.to_s.classify, view_serializer.type)
+        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
+      klass.send(:define_method, :serialize) do |object, options = {}|
+        final_serializer.serialize(object, options)
+      end
+      klass.send(:define_method, :type) do
+        final_serializer.type
+      end
+      klass.send(:define_singleton_method, :type) do
+        final_serializer.type
+      end
+      klass.send(:define_singleton_method, :serializer) do
+        klass.new
+      end
+
+      klass
+    end
+
+  end
+end

data/lib/sober_swag/compiler/error.rb

@@ -0,0 +1,5 @@
+module SoberSwag
+  class Compiler
+    class Error < ::SoberSwag::Error; end
+  end
+end

data/lib/sober_swag/compiler/path.rb

@@ -0,0 +1,80 @@
+module SoberSwag
+  class Compiler
+    ##
+    # Compile a singular path, and that's it.
+    # Only handles the actual body.
+    class Path
+      ##
+      # @param route [SoberSwag::Controller::Route] a route to use
+      # @param compiler [SoberSwag::Compiler] the compiler to use for type compilation
+      def initialize(route, compiler)
+        @route = route
+        @compiler = compiler
+      end
+
+      attr_reader :route, :compiler
+
+      def schema
+        base = {}
+        base[:summary] = route.summary if route.summary
+        base[:description] = route.description if route.description
+        base[:parameters] = params if params.any?
+        base[:responses] = responses
+        base[:requestBody] = request_body if request_body
+        base
+      end
+
+      def responses
+        route.response_serializers.map { |status, serializer|
+          [
+            status.to_s,
+            {
+              description: route.response_descriptions[status],
+              content: {
+                'application/json': {
+                  schema: compiler.response_for(
+                    serializer.respond_to?(:new) ? serializer.new.type : serializer.type
+                  )
+                }
+              }
+            }
+          ]
+        }.to_h
+      end
+
+      def params
+        query_params + path_params
+      end
+
+      def query_params
+        if route.query_params_class
+          compiler.query_params_for(route.query_params_class)
+        else
+          []
+        end
+      end
+
+      def path_params
+        if route.path_params_class
+          compiler.path_params_for(route.path_params_class)
+        else
+          []
+        end
+      end
+
+      def request_body
+        return nil unless route.request_body_class
+
+        {
+          required: true,
+          content: {
+            'application/json': {
+              schema: compiler.body_for(route.request_body_class)
+            }
+          }
+        }
+      end
+
+    end
+  end
+end

data/lib/sober_swag/compiler/paths.rb

@@ -0,0 +1,54 @@
+module SoberSwag
+  class Compiler
+    ##
+    # Compile multiple routes into a paths set.
+    class Paths
+      def initialize
+        @routes = []
+      end
+
+      def add_route(route)
+        @routes << route
+      end
+
+      def grouped_paths
+        routes.group_by(&:path)
+      end
+
+      ##
+      # Slightly weird method that gives you a compiled
+      # paths list. Since this is only a compiler for paths,
+      # it has *no idea* how to handle types. So, it takes a compiler
+      # which it will use to do that for it.
+      def paths_list(compiler)
+        grouped_paths.transform_values do |values|
+          values.map { |route|
+            [route.method, compile_route(route, compiler)]
+          }.to_h
+        end
+      end
+
+      ##
+      # Get a list of all types we discovered when compiling
+      # the paths.
+      def found_types
+        return enum_for(:found_types) unless block_given?
+
+        routes.each do |route|
+          %i[body_class query_class path_params_class].each do |k|
+            yield route.public_send(k) if route.public_send(k)
+          end
+        end
+      end
+
+      attr_reader :routes
+
+      private
+
+      def compile_route(route, compiler)
+        SoberSwag::Compiler::Path.new(route, compiler).schema
+      end
+
+    end
+  end
+end

data/lib/sober_swag/compiler/type.rb

@@ -0,0 +1,235 @@
+module SoberSwag
+  class Compiler
+    ##
+    # A compiler for DRY-Struct data types, essentially.
+    # It only consumes one type at a time.
+    class Type
+      class << self
+        def get_ref(klass)
+          "#/components/schemas/#{safe_name(klass)}"
+        end
+
+        def safe_name(klass)
+          klass.to_s.gsub('::', '.')
+        end
+
+        def primitive?(value)
+          primitive_def(value) != nil
+        end
+
+        def primitive_def(value)
+          return nil unless value.is_a?(Class)
+
+          if (name = primitive_name(value))
+            { type: name }
+          elsif value == Date
+            { type: 'string', format: 'date' }
+          elsif [Time, DateTime].any?(&value.ancestors.method(:include?))
+            { type: 'string', format: 'date-time' }
+          end
+        end
+
+        def primitive_name(value)
+          return 'null' if value == NilClass
+          return 'integer' if value == Integer
+          return 'number' if value == Float
+          return 'string' if value == String
+          return 'boolean' if [TrueClass, FalseClass].include?(value)
+        end
+      end
+
+      class TooComplicatedError < ::SoberSwag::Compiler::Error; end
+      class TooComplicatedForPathError < TooComplicatedError; end
+      class TooComplicatedForQueryError < TooComplicatedError; end
+
+      def initialize(type)
+        @type = type
+      end
+
+      attr_reader :type
+
+      ##
+      # Is this type standalone, IE, worth serializing on its own
+      # in the schemas section of our schema?
+      def standalone?
+        type.is_a?(Class)
+      end
+
+      def object_schema
+        @object_schema ||=
+          normalize(parsed_type).cata(&method(:to_object_schema))
+      end
+
+      def schema_stub
+        @schema_stub ||= generate_schema_stub
+      end
+
+      def path_schema
+        path_schema_stub.map { |e| e.merge(in: :path) }
+      rescue TooComplicatedError => e
+        raise TooComplicatedForPathError, e.message
+      end
+
+      def query_schema
+        path_schema_stub.map { |e| e.merge(in: :query) }
+      rescue TooComplicatedError => e
+        raise TooComplicatedForQueryError, e.message
+      end
+
+      def ref_name
+        self.class.safe_name(type)
+      end
+
+      def found_types
+        @found_types ||=
+          begin
+            (_, found_types) = parsed_result
+            found_types
+          end
+      end
+
+      def parsed_type
+        @parsed_type ||=
+          begin
+            (parsed, _)  = parsed_result
+            parsed
+          end
+      end
+
+      def parsed_result
+        @parsed_result ||= Parser.new(type_for_parser).run_parser
+      end
+
+      def eql?(other)
+        other.class == self.class && other.type == type
+      end
+
+      def hash
+        [self.class, type].hash
+      end
+
+      private
+
+      def generate_schema_stub
+        return self.class.primitive_def(type) if self.class.primitive?(type)
+
+        case type
+        when Class
+          { :$ref => self.class.get_ref(type) }
+        when Dry::Types::Constrained
+          self.class.new(type.type).schema_stub
+        when Dry::Types::Array::Member
+          { type: :array, items: self.class.new(type.member).schema_stub }
+        else
+          raise ArgumentError, "Cannot generate a schema stub for #{type} (#{type.class})"
+        end
+      end
+
+      def type_for_parser
+        if type.is_a?(Class)
+          type.schema.type
+        else
+          # Probably a constrained array
+          type
+        end
+      end
+
+      def normalize(object)
+        object.cata { |e| rewrite_sums(e) }.cata { |e| flatten_one_ofs(e) }
+      end
+
+      def rewrite_sums(object)
+        case object
+        in Nodes::Sum[Nodes::OneOf[*lhs], Nodes::OneOf[*rhs]]
+        Nodes::OneOf.new(lhs + rhs)
+        in Nodes::Sum[Nodes::OneOf[*args], rhs]
+        Nodes::OneOf.new(args + [rhs])
+        in Nodes::Sum[lhs, Nodes::OneOf[*args]]
+        Nodes::OneOf.new([lhs] + args)
+        in Nodes::Sum[lhs, rhs]
+        Nodes::OneOf.new([lhs, rhs])
+        else
+          object
+        end
+      end
+
+      def flatten_one_ofs(object)
+        case object
+          in Nodes::OneOf[*args]
+          Nodes::OneOf.new(args.uniq)
+        else
+          object
+        end
+      end
+
+      def to_object_schema(object)
+        case object
+        in Nodes::List[element]
+          {
+            type: :array,
+            items: element
+          }
+        in Nodes::Enum[values]
+          {
+            type: :string,
+            enum: values
+          }
+        in Nodes::OneOf[{ type: 'null' }, b]
+        b.merge(nullable: true)
+        in Nodes::OneOf[a, { type: 'null' }]
+        a.merge(nullable: true)
+        in Nodes::OneOf[*attrs] if attrs.include?(type: 'null')
+        { oneOf: attrs.reject { |e| e[:type] == 'null' }, nullable: true }
+        in Nodes::OneOf[*cases]
+        { oneOf: cases }
+        in Nodes::Object[*attrs]
+        # openAPI requires that you give a list of required attributes
+        # (which IMO is the *totally* wrong thing to do but whatever)
+        # so we must do this garbage
+        required = attrs.filter {|(_, b)| b[:required] }.map(&:first)
+        {
+          type: :object,
+          properties: attrs.map { |(a,b)|
+            [a, b.select { |k, _| k != :required }]
+          }.to_h,
+          required: required
+        }
+        in Nodes::Attribute[name, true, value]
+        [name, value.merge(required: true)]
+        in Nodes::Attribute[name, false, value]
+        [name, value]
+        # can't match on value directly as ruby uses `===` to match,
+        # and classes use `===` to mean `is an instance of`, as
+        # opposed to direct equality lmao
+        in Nodes::Primitive[value:] if self.class.primitive?(value)
+        self.class.primitive_def(value)
+        in Nodes::Primitive[value:]
+        { '$ref': self.class.get_ref(value) }
+        else
+          raise ArgumentError, "Got confusing node #{object} (#{object.class})"
+        end
+      end
+
+      def path_schema_stub
+        @path_schema_stub ||=
+          object_schema[:properties].map do |k, v|
+            ensure_uncomplicated(k, v)
+            {
+              name: k,
+              schema: v.reject { |k, _| %i[required nullable].include?(k) },
+              allowEmptyValue: !object_schema[:required].include?(k) || !!v[:nullable], # if it's required, no empties, but if *nullabe*, empties are okay
+              required: object_schema[:required].include?(k) || false,
+            }
+          end
+      end
+
+      def ensure_uncomplicated(key, value)
+        return if value[:type]
+        raise TooComplicatedError, <<~ERROR
+          Property #{key} has object-schema #{value}, but this type of param should be simple (IE a primitive of some kind)
+        ERROR
+      end
+
+    end
+  end
+end