sober_swag 0.15.0 → 0.20.0

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,27 @@ 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
       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/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/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.15.0'
+  VERSION = '0.20.0'
 end

data/sober_swag.gemspec

@@ -39,7 +39,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'pry-byebug'
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
-  spec.add_development_dependency 'rubocop'
-  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'rubocop', '~> 0.93.1'
+  spec.add_development_dependency 'rubocop-rspec', '~> 1.44.1'
   spec.add_development_dependency 'simplecov'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sober_swag
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.20.0
 platform: ruby
 authors:
 - Anthony Super
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-09-02 00:00:00.000000000 Z
+date: 2021-05-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -126,30 +126,30 @@ dependencies:
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.93.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.93.1
 - !ruby/object:Gem::Dependency
   name: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.44.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.44.1
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -172,6 +172,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/config/rubocop_linter_action.yml"
+- ".github/dependabot.yml"
 - ".github/workflows/lint.yml"
 - ".github/workflows/ruby.yml"
 - ".gitignore"
@@ -179,12 +180,14 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - ".travis.yml"
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - bin/console
+- bin/rspec
 - bin/setup
 - docs/serializers.md
 - example/.gitignore