sober_swag 0.18.0 → 0.22.0

data/lib/sober_swag/reporting/report/value.rb

@@ -0,0 +1,28 @@
+module SoberSwag
+  module Reporting
+    module Report
+      ##
+      # Report for a single value.
+      # Basically a wrapper around an array of strings.
+      class Value < Base
+        ##
+        # @param problems [Array<String>] problems with it
+        def initialize(problems)
+          @problems = problems
+        end
+
+        ##
+        # @return [Array<String>] the problems the value had
+        attr_reader :problems
+
+        def each_error
+          return enum_for(:each_error) unless block_given?
+
+          problems.each do |problem|
+            yield nil, problem
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sober_swag/reporting/report.rb

@@ -0,0 +1,16 @@
+module SoberSwag
+  module Reporting
+    ##
+    # Namespace modules for the various "reporters," or things that provide error handling.
+    module Report
+      autoload :Base, 'sober_swag/reporting/report/base'
+      autoload :Either, 'sober_swag/reporting/report/either'
+      autoload :Error, 'sober_swag/reporting/report/error'
+      autoload :Object, 'sober_swag/reporting/report/object'
+      autoload :Output, 'sober_swag/reporting/report/output'
+      autoload :MergedObject, 'sober_swag/reporting/report/merged_object'
+      autoload :Value, 'sober_swag/reporting/report/value'
+      autoload :List, 'sober_swag/reporting/report/list'
+    end
+  end
+end

data/lib/sober_swag/reporting.rb

@@ -0,0 +1,11 @@
+module SoberSwag
+  ##
+  # A new module for parsers with better error reporting.
+  module Reporting
+    autoload :Input, 'sober_swag/reporting/input'
+    autoload :Report, 'sober_swag/reporting/report'
+    autoload :Output, 'sober_swag/reporting/output'
+    autoload :Compiler, 'sober_swag/reporting/compiler'
+    autoload :InvalidSchemaError, 'sober_swag/reporting/invalid_schema_error'
+  end
+end

data/lib/sober_swag/serializer/array.rb

@@ -1,30 +1,54 @@
 module SoberSwag
   module Serializer
     ##
-    # Make a serialize of arrays out of a serializer of the elements
+    # Transform a serializer that works on elements to one that works on Arrays
     class Array < Base
+      ##
+      # Make an array serializer out of another serializer.
+      # @param element_serializer [SoberSwag::Serializer::Base] the serializer to use for each element.
       def initialize(element_serializer)
         @element_serializer = element_serializer
       end
 
+      ##
+      # The serializer that will be used for each element in the array.
+      #
+      # @return [SoberSwag::Serializer::Base]
+      attr_reader :element_serializer
+
+      ##
+      # Delegates to {#element_serializer}
       def lazy_type?
         @element_serializer.lazy_type?
       end
 
+      ##
+      # Delegates to {#element_serializer}, wrapped in an array
       def lazy_type
         SoberSwag::Types::Array.of(@element_serializer.lazy_type)
       end
 
+      ##
+      # Delegates to {#element_serializer}
       def finalize_lazy_type!
         @element_serializer.finalize_lazy_type!
       end
 
-      attr_reader :element_serializer
-
+      ##
+      # Serialize an array of objects that can be serialized with {#element_serializer}
+      # by calling `element_serializer.serialize` for each item in this array.
+      #
+      # Note: since ruby is duck-typed, anything that responds to the `#map` method from
+      # [Enumerable](https://ruby-doc.org/core-3.0.0/Enumerable.html) should work!
+      #
+      # @param object [Array<Object>,#map] collection of objects to serialize
+      # @return [Array<Object>] JSON-compatible array
       def serialize(object, options = {})
         object.map { |a| element_serializer.serialize(a, options) }
       end
 
+      ##
+      # The type of items returned from {#serialize}
       def type
         SoberSwag::Types::Array.of(element_serializer.type)
       end

data/lib/sober_swag/serializer/base.rb

@@ -1,34 +1,91 @@
 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.
+    # Base class for everything that provides serialization functionality in SoberSwag.
+    # SoberSwag serializers transform Ruby types into JSON types, with some associated *schema*.
+    # This schema is then used in the generated OpenAPI V3 documentation.
     class Base
       ##
       # Return a new serializer that is an *array* of elements of this serializer.
+      # This serializer will take in an array, and use `self` to serialize every element.
+      #
+      # @return [SoberSwag::Serializer::Array]
       def array
         SoberSwag::Serializer::Array.new(self)
       end
 
       ##
-      # Returns a serializer that will pass `nil` values on unscathed
+      # Returns a serializer that will pass `nil` values on unscathed.
+      # That means that if you try to serialize `nil` with it, it will result in a JSON `null`.
+      # @return [SoberSwag::Serializer::Optional]
       def optional
         SoberSwag::Serializer::Optional.new(self)
       end
 
       alias nilable optional
 
+      ##
+      # Add metadata onto the *type* of a serializer.
+      # Note that this *returns a new serializer with metadata added* and does not perform mutation.
+      # @param hash [Hash] the metadata to set.
+      # @return [SoberSwag::Serializer::Meta] a serializer with metadata added
+      def meta(hash)
+        SoberSwag::Serializer::Meta.new(self, hash)
+      end
+
+      ##
+      # Get a new serializer that will first run the given block before serializing an object.
+      # For example, if you have a serializer for strings called `StringSerializer`,
+      # and you want to serialize `Date` objects via encoding them to a standardized string format,
+      # you can use:
+      #
+      # ```
+      #   DateSerializer = StringSerializer.via_map do |date|
+      #     date.strftime('%Y-%m-%d')
+      #   end
+      # ```
+      #
+      # @yieldparam [Object] the object before serialization
+      # @yieldreturn [Object] a transformed object, that will
+      #   be passed to {#serialize}
+      # @return [SoberSwag::Serializer::Mapped] the new serializer
+      def via_map(&block)
+        SoberSwag::Serializer::Mapped.new(self, block)
+      end
+
       ##
       # Is this type lazily defined?
       #
-      # Used for mutual recursion.
+      # If we have two serializers that are *mutually recursive*, we need to do some "fun" magic to make that work.
+      # This comes up in a case like:
+      #
+      # ```ruby
+      #   SchoolClass = SoberSwag::OutputObject.define do
+      #     field :name, primitive(:String)
+      #     view :detail do
+      #       field :students, -> { Student.view(:base) }
+      #     end
+      #   end
+      #
+      #   Student = SoberSwag::OutputObject.define do
+      #     field :name, primitive(:String)
+      #     view :detail do
+      #       field :classes, -> { SchoolClass.view(:base) }
+      #     end
+      #   end
+      # ```
+      #
+      # This would result in an infinite loop if we tried to define the type struct the easy way.
+      # So, we instead use mutation to achieve "laziness."
       def lazy_type?
         false
       end
 
       ##
       # The lazy version of this type, for mutual recursion.
+      # @see #lazy_type? for why this is needed
+      #
+      # Once you call {#finalize_lazy_type!}, the type will be "fleshed out," and can be actually used.
       def lazy_type
         type
       end
@@ -43,43 +100,36 @@ module SoberSwag
 
       ##
       # Serialize an object.
+      # @abstract
       def serialize(_object, _options = {})
         raise ArgumentError, 'not implemented!'
       end
 
       ##
       # Get the type that we serialize to.
+      # @abstract
       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.
-      # For example, if I am a serializer for {String}, and you know how to turn
-      # an {Int} into a {String}, I can now serialize {Int}s (by turning them into a string).
+      # Returns self.
       #
-      # Note that the *declared* type of this is *not* changed: from a user's perspective,
-      # they see a "string"
-      def via_map(&block)
-        SoberSwag::Serializer::Mapped.new(self, block)
-      end
-
-      ##
-      # Serializer lets you get a serializer from things that might be classes
-      # because of the blueprint naming hack.
+      # This exists due to a hack.
       def serializer
         self
       end
 
       ##
-      # Get the type name of this to be used externally, or set it if an argument is provided
+      # @overload identifier()
+      #   Returns the external identifier, used to uniquely identify this object within
+      #   the schemas section of an OpenAPI v3 document.
+      #   @return [String] the identifier.
+      # @overload identifier(arg)
+      #   Sets the external identifier to use to uniquely identify
+      #   this object within the schemas section of an OpenAPI v3 document.
+      #   @param arg [String] the identifier to use
+      #   @return [String] the identifer set
       def identifier(arg = nil)
         @identifier = arg if arg
         @identifier

data/lib/sober_swag/serializer/conditional.rb

@@ -10,19 +10,49 @@ module SoberSwag
     # This is a very weird, not-very-Ruby-like abstraction, *upon which* we can build abstractions that are actually use for users.
     # It lets you build abstractions like "Use this serializer if a type has this class, otherwise use this other one."
     # When composed together, you can make arbitrary decision trees.
+    #
+    # This class is heavily inspired by
+    # the [Decideable](https://hackage.haskell.org/package/contravariant-1.5.3/docs/Data-Functor-Contravariant-Divisible.html#t:Decidable)
+    # typeclass from Haskell.
     class Conditional < Base
       ##
       # Error thrown when a chooser proc returns a non left-or-right value.
       class BadChoiceError < Error; end
 
+      ##
+      # Create a new conditional serializer, from a "chooser" proc, a "left" serializer, and a "right" serializer.
+      #
+      # @param chooser [Proc,Lambda] the proc that chooses which "side" to use
+      # @param left [SoberSwag::Serializer::Base] a serializer for the "left" side
+      # @param right [SoberSwag::Serializer::Base] a serializer for the "right" side
       def initialize(chooser, left, right)
         @chooser = chooser
         @left = left
         @right = right
       end
 
-      attr_reader :chooser, :left, :right
+      ##
+      # @return [Proc,Lambda] the "chooser" proc.
+      attr_reader :chooser
+
+      ##
+      # @return [SoberSwag::Serializer::Base] the serializer to use if the "chooser" proc chooses `:right`.
+      #   Also called the "left-side serializer."
+      attr_reader :left
 
+      ##
+      # @return [SoberSwag::Serializer::Base] the serializer to use if the "chooser" proc chooses `:right`.
+      #   Also called the "right-side serializer."
+      attr_reader :right
+
+      ##
+      # First, call {#chooser} with `object` and `options` to see what serializer to use, and *what* to serialize.
+      # Then, if it returns `[:left, val]`, use {#left} to serialize `val`.
+      # Otherwise, if it returns `[:right, val]`, use {#right} to serialize `val`.
+      # If it returns neither, throw {BadChoiceError}.
+      #
+      # @raise [BadChoiceError] if {#chooser} did not choose what side to use
+      # @return [Hash] a JSON-compatible object
       def serialize(object, options = {})
         tag, val = chooser.call(object, options)
         case tag
@@ -58,6 +88,8 @@ module SoberSwag
         left.lazy_type? || right.lazy_type?
       end
 
+      ##
+      # Finalize both {#left} and {#right}
       def finalize_lazy_type!
         [left, right].each(&:finalize_lazy_type!)
       end

data/lib/sober_swag/serializer/field_list.rb

@@ -1,13 +1,18 @@
 module SoberSwag
   module Serializer
     ##
-    # Extract out a hash from a list of
-    # name/serializer pairs.
+    # Extracts a JSON hash from a list of {SoberSwag::OutputObject::Field} structs.
     class FieldList < Base
+      ##
+      # Create a new field-list serializer.
+      #
+      # @param field_list [Array<SoberSwag::OutputObject::Field>] descriptions of each field
       def initialize(field_list)
         @field_list = field_list
       end
 
+      ##
+      # @return [Array<SoberSwag::OutputObject::Field>] the list of fields to use.
       attr_reader :field_list
 
       ##
@@ -16,16 +21,29 @@ module SoberSwag
         SoberSwag::Serializer.Primitive(SoberSwag::Types.const_get(symbol))
       end
 
+      ##
+      # Serialize an object to a JSON hash by using each field in the list.
+      # @param object [Object] object to serialize
+      # @param options [Hash] arbitrary options
+      # @return [Hash] serialized object.
       def serialize(object, options = {})
-        field_list.map { |field|
-          [field.name, field.serializer.serialize(object, options)]
-        }.to_h
+        {}.tap do |hash|
+          field_list.each do |field|
+            hash[field.name] = field.serializer.serialize(object, options)
+          end
+        end
       end
 
+      ##
+      # Construct a Dry::Struct from the fields given.
+      # This Struct will be swagger-able.
+      # @return [Dry::Struct]
       def type
         @type ||= make_struct_type!
       end
 
+      ##
+      # These types are always constructed lazily.
       def lazy_type?
         true
       end

data/lib/sober_swag/serializer/hash.rb

@@ -0,0 +1,53 @@
+require 'set'
+
+module SoberSwag
+  module Serializer
+    ##
+    # Serialize via hash lookup.
+    # This is used to speed up serialization of views, but it may be useful elsewhere.
+    #
+    class Hash < Base
+      ##
+      # @param choices [Hash<Object => SoberSwag::Serializer::Base>] hash of serializers
+      #   that we might use.
+      # @param default [SoberSwag::Serializer::Base] default to use if key not found.
+      # @param key_proc [Proc<Object, Hash>] extract the key we are interested in from the proc.
+      #   Will be called with the object to serialize and the options hash.
+      def initialize(choices, default, key_proc)
+        @choices = choices
+        @default = default
+        @key_proc = key_proc
+      end
+
+      attr_reader :choices, :default, :key_proc
+
+      def serialize(object, options = {})
+        key = key_proc.call(object, options)
+
+        choices.fetch(key) { default }.serialize(object, options)
+      end
+
+      ##
+      # @return [Set<SoberSwag::Serializer::Base>]
+      def possible_serializers
+        @possible_serializers ||= (choices.values + [default]).to_set
+      end
+
+      def lazy_type?
+        possible_serializers.any?(&:lazy_type?)
+      end
+
+      def finalize_lazy_type!
+        possible_serializers.each(&:finalize_lazy_type!)
+      end
+
+      def lazy_type
+        @lazy_type ||= possible_serializers.map(&:lazy_type).reduce(:|)
+      end
+
+      def type
+        @type ||= possible_serializers.map(&:type).reduce(:|)
+      end
+    end
+  end
+end

data/lib/sober_swag/serializer/mapped.rb

@@ -3,12 +3,21 @@ module SoberSwag
     ##
     # A new serializer by mapping over the serialization function
     class Mapped < Base
+      ##
+      # Create a new mapped serializer.
+      # @param base [SoberSwag::Serializer::Base] a serializer to use after mapping
+      # @param map_f [Proc,Lambda] a mapping function to use before serialization
       def initialize(base, map_f)
         @base = base
         @map_f = map_f
       end
 
-      attr_reader :base, :map_f
+      ##
+      # @return [SoberSwag::Serializer::Base] serializer to use after mapping
+      attr_reader :base
+      ##
+      # @return [Proc, Lambda, #call] function to use before serialization
+      attr_reader :map_f
 
       def serialize(object, options = {})
         @base.serialize(@map_f.call(object), options)

data/lib/sober_swag/serializer/optional.rb

@@ -5,11 +5,20 @@ module SoberSwag
     # this can be used to make a serializer of type 'A | nil'.
     #
     # Or, put another way, makes serializers not crash on nil values.
+    # If {#serialize} is passed nil, it will return `nil` immediately, and not
+    # try to call the serializer of {#inner}.
     class Optional < Base
+      ##
+      # An error thrown when trying to nest optional serializers.
+      class NestedOptionalError < Error; end
+      ##
+      # @param inner [SoberSwag::Serializer::Base] the serializer to use for non-nil values
       def initialize(inner)
         @inner = inner
       end
 
+      ##
+      # @return [SoberSwag::Serializer::Base] the serializer to use for non-nil values.
       attr_reader :inner
 
       def lazy_type?
@@ -24,6 +33,9 @@ module SoberSwag
         @inner.finalize_lazy_type!
       end
 
+      ##
+      # If `object` is nil, return `nil`.
+      # Otherwise, call `inner.serialize(object, options)`.
       def serialize(object, options = {})
         if object.nil?
           object
@@ -36,8 +48,13 @@ module SoberSwag
         inner.type.optional
       end
 
+      ##
+      # Since nesting optional types is bad, this will always raise an ArgumentError
+      #
+      # @raise [NestedOptionalError] always
+      # @return [void] nothing, always raises.
       def optional(*)
-        raise ArgumentError, 'no nesting optionals please'
+        raise NestedOptionalError, 'no nesting optionals please'
       end
     end
   end

data/lib/sober_swag/serializer/primitive.rb

@@ -4,6 +4,9 @@ module SoberSwag
     # A class that does *no* serialization: you give it a type,
     # and it will pass any serialized input on verbatim.
     class Primitive < Base
+      ##
+      # Construct a primitive serializer with a description of the type it serializes to.
+      # @param type [Class] a swagger-able type
       def initialize(type)
         @type = type
       end

data/lib/sober_swag/serializer.rb

@@ -10,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(:Hash, 'sober_swag/serializer/hash')
     autoload(:Meta, 'sober_swag/serializer/meta')
 
     class << self

data/lib/sober_swag/server.rb

@@ -21,42 +21,58 @@ module SoberSwag
     # 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)
+    # @param cache [Bool | Proc] if we should cache our definitions (default false)
+    # @param redoc_version [String] what version of the redoc library to use to display UI (default 'next', the latest version).
     def initialize(
       controller_proc: RAILS_CONTROLLER_PROC,
-      cache: false
+      cache: false,
+      redoc_version: 'next'
     )
       @controller_proc = controller_proc
       @cache = cache
+      @html = EFFECT_HTML.gsub(/REDOC_VERSION/, redoc_version)
     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>
+          <title>ReDoc</title>
+          <!-- needed for adaptive design -->
+          <meta charset="utf-8"/>
+          <meta name="viewport" content="width=device-width, initial-scale=1">
+          <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+
+          <!--
+          ReDoc doesn't change outer page styles
+          -->
+          <style>
+            body {
+              margin: 0;
+              padding: 0;
+            }
+          </style>
         </head>
         <body>
-          <div id="swagger">
-          </div>
-          <script>
-            SwaggerUIBundle({url: 'SCRIPT_NAME', dom_id: '#swagger'})
-          </script>
+          <redoc spec-url='SCRIPT_NAME'></redoc>
+          <script src="https://cdn.jsdelivr.net/npm/redoc@REDOC_VERSION/bundles/redoc.standalone.js"> </script>
         </body>
       </html>
     HTML
 
+    ##
+    # Standard Rack call method.
     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')]]
+        [200, { 'Content-Type' => 'text/html' }, [@html.gsub(/SCRIPT_NAME/, "#{env['SCRIPT_NAME']}.json")]]
       end
     end
 
+    private
+
     def generate_json_string
       if cache?
         @json_string ||= JSON.dump(generate_swagger)

data/lib/sober_swag/type/named.rb

@@ -9,24 +9,38 @@ module SoberSwag
       # Modules that include {SoberSwag::Type::Named}
       # will automatically extend this module.
       module ClassMethods
+        ##
+        # Is this type a "wrapper" for another type?
         def alias?
           false
         end
 
+        ##
+        # The type this type is a wrapper for
         def alias_of
           nil
         end
 
+        ##
+        # The "root" type along the alias chain
         def root_alias
           alias_of || self
         end
 
+        ##
+        # @overload description()
+        #   @return [String] a human-readable description of this type
+        # @overload description(arg)
+        #   @param arg [String] a human-readable description of this type
+        #   @return [String] `arg`
         def description(arg = nil)
           @description = arg if arg
           @description
         end
       end
 
+      ##
+      # When included, extends {SoberSwag::Type::Named::ClassMethods}
       def self.included(mod)
         mod.extend(ClassMethods)
       end

data/lib/sober_swag/types/comma_array.rb

@@ -3,6 +3,10 @@ module SoberSwag
     ##
     # An array that will be parsed from comma-separated values in a string, if given a string.
     module CommaArray
+      ##
+      # Get a parser that will parse comma-separated values of another type.
+      # @param other [Class] a swagger-able type to parse into
+      # @return [SoberSwag::Types::CommaArray]
       def self.of(other)
         SoberSwag::Types::Array.of(other).constructor { |val|
           if val.is_a?(::String)

data/lib/sober_swag/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SoberSwag
-  VERSION = '0.18.0'
+  VERSION = '0.22.0'
 end