sober_swag 0.1.0 → 0.2.0

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

@@ -1,14 +1,16 @@
 module SoberSwag
-  class Blueprint
+  class OutputObject
+    ##
+    # DSL for defining a view.
+    # Used in `view` blocks within {SoberSwag::OutputObject.define}.
     class View
-
       def self.define(name, base_fields, &block)
-        self.new(name, base_fields).tap do |view|
+        new(name, base_fields).tap do |view|
           view.instance_eval(&block)
         end
       end
 
-      class NestingError < Error; end;
+      class NestingError < Error; end
 
       include FieldSyntax
 
@@ -19,8 +21,16 @@ module SoberSwag
 
       attr_reader :name, :fields
 
+      def serialize(obj, opts = {})
+        serializer.serialize(obj, opts)
+      end
+
+      def type
+        serializer.type
+      end
+
       def except!(name)
-        @fields.select! { |f| f.name != name }
+        @fields.reject! { |f| f.name == name }
       end
 
       def view(*)
@@ -38,7 +48,6 @@ module SoberSwag
         @serializer ||=
           SoberSwag::Serializer::FieldList.new(fields)
       end
-
     end
   end
 end

data/lib/sober_swag/parser.rb

@@ -1,11 +1,14 @@
 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.
   class Parser
     def initialize(node)
       @node = node
       @found = Set.new
     end
 
-    def to_syntax
+    def to_syntax # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
       case @node
       when Dry::Types::Array::Member
         Nodes::List.new(bind(Parser.new(@node.member)))
@@ -41,7 +44,7 @@ module SoberSwag
         bind(Parser.new(@node.type))
       when Dry::Types::Nominal
         # start off with the moral equivalent of NodeTree[String]
-        Nodes::Primitive.new(@node.primitive)
+        Nodes::Primitive.new(@node.primitive, @node.meta)
       else
         # Inside of this case we have a class that is some user-defined type
         # We put it in our array of found types, and consider it a primitive
@@ -68,6 +71,5 @@ module SoberSwag
       @found += other.found
       result
     end
-
   end
 end

data/lib/sober_swag/serializer.rb

@@ -1,4 +1,7 @@
 module SoberSwag
+  ##
+  # Container module for serializers.
+  # The interface for these is described in {SoberSwag::Serializer::Base}.
   module Serializer
     autoload(:Base, 'sober_swag/serializer/base')
     autoload(:Primitive, 'sober_swag/serializer/primitive')
@@ -7,6 +10,7 @@ module SoberSwag
     autoload(:Mapped, 'sober_swag/serializer/mapped')
     autoload(:Optional, 'sober_swag/serializer/optional')
     autoload(:FieldList, 'sober_swag/serializer/field_list')
+    autoload(:Meta, 'sober_swag/serializer/meta')
 
     class << self
       ##
@@ -14,10 +18,9 @@ module SoberSwag
       # in values raw.
       #
       # @param contained {Class} Dry::Type to use
-      def Primitive(contained)
+      def Primitive(contained) # rubocop:disable Naming/MethodName
         SoberSwag::Serializer::Primitive.new(contained)
       end
     end
-
   end
 end

data/lib/sober_swag/serializer/array.rb

@@ -7,6 +7,18 @@ module SoberSwag
         @element_serializer = element_serializer
       end
 
+      def lazy_type?
+        @element_serializer.lazy_type?
+      end
+
+      def lazy_type
+        SoberSwag::Types::Array.of(@element_serializer.lazy_type)
+      end
+
+      def finalize_lazy_type!
+        @element_serializer.finalize_lazy_type!
+      end
+
       attr_reader :element_serializer
 
       def serialize(object, options = {})

data/lib/sober_swag/serializer/base.rb

@@ -1,7 +1,10 @@
 module SoberSwag
   module Serializer
+    ##
+    # Base interface class that all other serializers are subclasses of.
+    # This also defines methods as stubs, which is sort of bad ruby style, but makes documentation
+    # easier to generate.
     class Base
-
       ##
       # Return a new serializer that is an *array* of elements of this serializer.
       def array
@@ -14,6 +17,46 @@ module SoberSwag
         SoberSwag::Serializer::Optional.new(self)
       end
 
+      ##
+      # Is this type lazily defined?
+      #
+      # Used for mutual recursion.
+      def lazy_type?
+        false
+      end
+
+      ##
+      # The lazy version of this type, for mutual recursion.
+      def lazy_type
+        type
+      end
+
+      ##
+      # Finalize a lazy type.
+      #
+      # Should be idempotent: call it once, and it does nothing on subsequent calls (but returns the type).
+      def finalize_lazy_type!
+        type
+      end
+
+      ##
+      # Serialize an object.
+      def serialize(_object, _options = {})
+        raise ArgumentError, 'not implemented!'
+      end
+
+      ##
+      # Get the type that we serialize to.
+      def type
+        raise ArgumentError, 'not implemented!'
+      end
+
+      ##
+      # Add metadata onto the *type* of a serializer.
+      def meta(hash)
+        SoberSwag::Serializer::Meta.new(self, hash)
+      end
+
       ##
       # If I am a serializer for type 'a', and you give me a way to turn 'a's into 'b's,
       # I can give you a serializer for type 'b' by running the funciton you gave.
@@ -33,6 +76,12 @@ module SoberSwag
         self
       end
 
+      ##
+      # Get the type name of this to be used externally, or set it if an argument is provided
+      def identifier(arg = nil)
+        @identifier = arg if arg
+        @identifier
+      end
     end
   end
 end

data/lib/sober_swag/serializer/conditional.rb

@@ -25,9 +25,10 @@ module SoberSwag
 
       def serialize(object, options = {})
         tag, val = chooser.call(object, options)
-        if tag == :left
+        case tag
+        when :left
           left.serialize(val, options)
-        elsif tag == :right
+        when :right
           right.serialize(val, options)
         else
           raise BadChoiceError, "result of chooser proc was not a left or right, but a #{val.class}"
@@ -44,6 +45,18 @@ module SoberSwag
           left.type | right.type
         end
       end
+
+      def lazy_type
+        left.lazy_type | right.lazy_type
+      end
+
+      def lazy_type?
+        left.lazy_type? || right.lazy_type?
+      end
+
+      def finalize_lazy_type!
+        [left, right].each(&:finalize_lazy_type!)
+      end
     end
   end
 end

data/lib/sober_swag/serializer/field_list.rb

@@ -4,7 +4,6 @@ module SoberSwag
     # Extract out a hash from a list of
     # name/serializer pairs.
     class FieldList < Base
-
       def initialize(field_list)
         @field_list = field_list
       end
@@ -17,8 +16,7 @@ module SoberSwag
         SoberSwag::Serializer.Primitive(SoberSwag::Types.const_get(symbol))
       end
 
-
-      def serialize(object, options)
+      def serialize(object, options = {})
         field_list.map { |field|
           [field.name, field.serializer.serialize(object, options)]
         }.to_h
@@ -28,17 +26,42 @@ module SoberSwag
         @type ||= make_struct_type!
       end
 
+      def lazy_type?
+        true
+      end
+
+      def lazy_type
+        struct_class
+      end
+
+      def finalize_lazy_type!
+        make_struct_type!
+      end
+
       private
 
-      def make_struct_type!
+      def make_struct_type! # rubocop:disable Metrics/MethodLength
+        # mutual recursion makes this really, really annoying.
+        return struct_class if @made_struct_type
+
         f = field_list
-        Class.new(Dry::Struct) do
+        s = identifier
+        struct_class.instance_eval do
+          identifier(s)
           f.each do |field|
-            attribute field.name, field.serializer.type
+            attribute field.name, field.serializer.lazy_type
           end
         end
+        @made_struct_type = true
+
+        field_list.map(&:serializer).each(&:finalize_lazy_type!)
+
+        struct_class
       end
 
+      def struct_class
+        @struct_class ||= Class.new(SoberSwag::InputObject)
+      end
     end
   end
 end

data/lib/sober_swag/serializer/mapped.rb

@@ -3,7 +3,6 @@ module SoberSwag
     ##
     # A new serializer by mapping over the serialization function
     class Mapped < Base
-
       def initialize(base, map_f)
         @base = base
         @map_f = map_f
@@ -13,6 +12,18 @@ module SoberSwag
         @base.serialize(@map_f.call(object), options)
       end
 
+      def lazy_type?
+        @base.lazy_type?
+      end
+
+      def lazy_type
+        @base.lazy_type
+      end
+
+      def finalize_lazy_type!
+        @base.finalize_lazy_type!
+      end
+
       def type
         @base.type
       end
@@ -23,7 +34,6 @@ module SoberSwag
       def via_map(&block)
         SoberSwag::Serializer::Mapped.new(@base, @map_f >> block)
       end
-
     end
   end
 end

data/lib/sober_swag/serializer/meta.rb

@@ -0,0 +1,35 @@
+module SoberSwag
+  module Serializer
+    ##
+    # Provides metadata on a serializer.
+    # All actions delegate to the base.
+    class Meta < Base
+      def initialize(base, meta)
+        @base = base
+        @meta = meta
+      end
+
+      attr_reader :base, :meta
+
+      def serialize(args, opts = {})
+        base.serialize(args, opts)
+      end
+
+      def lazy_type
+        @base.lazy_type.meta(**meta)
+      end
+
+      def type
+        @base.type.meta(**meta)
+      end
+
+      def finalize_lazy_type!
+        @base.finalize_lazy_type!
+      end
+
+      def lazy_type?
+        @base.lazy_type?
+      end
+    end
+  end
+end

data/lib/sober_swag/serializer/optional.rb

@@ -1,13 +1,29 @@
 module SoberSwag
   module Serializer
+    ##
+    # Given something that serializes a type 'A',
+    # this can be used to make a serializer of type 'A | nil'.
+    #
+    # Or, put another way, makes serializers not crash on nil values.
     class Optional < Base
-
       def initialize(inner)
         @inner = inner
       end
 
       attr_reader :inner
 
+      def lazy_type?
+        @inner.lazy_type?
+      end
+
+      def lazy_type
+        @inner.lazy_type.optional
+      end
+
+      def finalize_lazy_type!
+        @inner.finalize_lazy_type!
+      end
+
       def serialize(object, options = {})
         if object.nil?
           object
@@ -23,7 +39,6 @@ module SoberSwag
       def optional(*)
         raise ArgumentError, 'no nesting optionals please'
       end
-
     end
   end
 end

data/lib/sober_swag/serializer/primitive.rb

@@ -1,5 +1,8 @@
 module SoberSwag
   module Serializer
+    ##
+    # A class that does *no* serialization: you give it a type,
+    # and it will pass any serialized input on verbatim.
     class Primitive < Base
       def initialize(type)
         @type = type
@@ -7,7 +10,7 @@ module SoberSwag
 
       attr_reader :type
 
-      def serialize(object, options = {})
+      def serialize(object, _options = {})
         object
       end
     end

data/lib/sober_swag/server.rb

@@ -0,0 +1,83 @@
+require 'set'
+
+module SoberSwag
+  ##
+  # A basic, rack-only server to serve up swagger definitions.
+  # By default it is configured to work with rails, but you can pass stuff to initialize.
+  class Server
+    RAILS_CONTROLLER_PROC = proc do
+      Rails.application.routes.routes.map { |route|
+        route.defaults[:controller]
+      }.to_set.reject(&:nil?).map { |controller|
+        "#{controller}_controller".classify.constantize
+      }.filter { |controller| controller.ancestors.include?(SoberSwag::Controller) }
+    end
+
+    ##
+    # Start up.
+    #
+    # @param controller_proc [Proc] a proc that, when called, gives a list of {SoberSwag::Controller}s to document
+    # @param cache [Bool | Proc] if we should cache our defintions (default false)
+    def initialize(
+      controller_proc: RAILS_CONTROLLER_PROC,
+      cache: false
+    )
+      @controller_proc = controller_proc
+      @cache = cache
+    end
+
+    EFFECT_HTML = <<~HTML.freeze
+      <!DOCTYPE html>
+      <html>
+        <head>
+          <title>Swagger-UI</title>
+          <script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
+          <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@3.23.4/swagger-ui.css"></link>
+        </head>
+        <body>
+          <div id="swagger">
+          </div>
+          <script>
+            SwaggerUIBundle({url: 'SCRIPT_NAME', dom_id: '#swagger'})
+          </script>
+        </body>
+      </html>
+    HTML
+
+    def call(env)
+      req = Rack::Request.new(env)
+      if req.path_info&.match?(/json/si) || req.get_header('Accept')&.match?(/json/si)
+        [200, { 'Content-Type' => 'application/json' }, [generate_json_string]]
+      else
+        [200, { 'Content-Type' => 'text/html' }, [EFFECT_HTML.gsub(/SCRIPT_NAME/, env['SCRIPT_NAME'] + '.json')]]
+      end
+    end
+
+    def generate_json_string
+      if cache?
+        @json_string ||= JSON.dump(generate_swagger)
+      else
+        JSON.dump(generate_swagger)
+      end
+    end
+
+    def cache?
+      @cache.respond_to?(:call) ? @cache.call : @cache
+    end
+
+    def generate_swagger
+      routes = sober_controllers.flat_map(&:defined_routes).reduce(SoberSwag::Compiler.new) { |c, r| c.add_route(r) }
+      {
+        openapi: '3.0.0',
+        info: {
+          version: '1',
+          title: 'SoberSwag Swagger'
+        }
+      }.merge(routes.to_swagger)
+    end
+
+    def sober_controllers
+      @controller_proc.call
+    end
+  end
+end