sober_swag 0.14.0 → 0.19.0

data/lib/sober_swag/controller.rb

@@ -17,12 +17,6 @@ module SoberSwag
       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.
@@ -96,7 +90,7 @@ module SoberSwag
           r = current_action_def
           raise UndefinedPathError unless r&.path_params_class
 
-          r.path_params_class.new(request.path_parameters)
+          r.path_params_class.call(request.path_parameters)
         end
     end
 
@@ -110,7 +104,7 @@ module SoberSwag
           r = current_action_def
           raise UndefinedBodyError unless r&.request_body_class
 
-          r.request_body_class.new(body_params)
+          r.request_body_class.call(body_params)
         end
     end
 
@@ -124,7 +118,7 @@ module SoberSwag
           r = current_action_def
           raise UndefinedQueryError unless r&.query_params_class
 
-          r.query_params_class.new(request.query_parameters)
+          r.query_params_class.call(request.query_parameters)
         end
     end
 

data/lib/sober_swag/controller/route.rb

@@ -9,28 +9,36 @@ module SoberSwag
         @action_name = action_name
         @response_serializers = {}
         @response_descriptions = {}
+        @tags = []
       end
 
       attr_reader :response_serializers, :response_descriptions, :controller, :method, :path, :action_name
 
       ##
-      # What to parse the request body in to.
+      # What to parse the request body into.
       attr_reader :request_body_class
       ##
-      # What to parse the request query_params in to
+      # What to parse the request query_params into.
       attr_reader :query_params_class
-
       ##
-      # What to parse the path params into
+      # What to parse the path params into.
       attr_reader :path_params_class
 
+      ##
+      # Standard swagger tags.
+      def tags(*args)
+        return @tags if args.empty?
+
+        @tags = args.flatten
+      end
+
       ##
       # 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 {SoberSwag::InputObject}.)
       # If you want, you can also define utility methods in here
       def request_body(base = SoberSwag::InputObject, &block)
         @request_body_class = make_input_object!(base, &block)
-        action_module.const_set('ResponseBody', @request_body_class)
+        action_module.const_set('RequestBody', @request_body_class)
       end
 
       ##
@@ -103,7 +111,7 @@ module SoberSwag
       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)
+        raise ArgumentError, 'Response defined!' if @response_serializers.key?(status_key)
 
         serializer ||= SoberSwag::OutputObject.define(&block)
         response_module.const_set(status_code.to_s.classify, serializer)
@@ -124,8 +132,22 @@ module SoberSwag
       end
 
       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)
+        if base.is_a?(Class)
+          make_input_class(base, block)
+        elsif block
+          raise ArgumentError, 'passed a non-class base and a block to an input'
+        else
+          base
+        end
+      end
+
+      def make_input_class(base, block)
+        if block
+          Class.new(base, &block).tap do |e|
+            e.transform_keys(&:to_sym) if [SoberSwag::InputObject, Dry::Struct].include?(base)
+          end
+        else
+          base
         end
       end
     end

data/lib/sober_swag/input_object.rb

@@ -7,6 +7,7 @@ module SoberSwag
   # Please see the documentation for that class to see how it works.
   class InputObject < Dry::Struct
     transform_keys(&:to_sym)
+    include SoberSwag::Type::Named
 
     class << self
       ##
@@ -17,19 +18,51 @@ module SoberSwag
         @identifier || name.to_s.gsub('::', '.')
       end
 
+      def attribute(key, parent = SoberSwag::InputObject, &block)
+        raise ArgumentError, "parent class #{parent} is not an input object type!" unless valid_field_def?(parent, block)
+
+        super(key, parent, &block)
+      end
+
+      def attribute?(key, parent = SoberSwag::InputObject, &block)
+        raise ArgumentError, "parent class #{parent} is not an input object type!" unless valid_field_def?(parent, block)
+
+        super(key, parent, &block)
+      end
+
       def meta(*args)
+        original = self
+
         super(*args).tap do |result|
-          result.identifier(identifier) if result.is_a?(Class) # pass on identifier
+          return result unless result.is_a?(Class)
+
+          result.define_singleton_method(:alias?) { true }
+          result.define_singleton_method(:alias_of) { original }
         end
       end
 
-      def primitive(sym)
-        SoberSwag::Types.const_get(sym)
+      ##
+      # .primitive is already defined on Dry::Struct, so forward to the superclass if
+      # not called as a way to get a primitive type
+      def primitive(*args)
+        if args.length == 1
+          SoberSwag::Types.const_get(args.first)
+        else
+          super
+        end
       end
 
       def param(sym)
         SoberSwag::Types::Params.const_get(sym)
       end
+
+      private
+
+      def valid_field_def?(parent, block)
+        return true if block.nil?
+
+        parent.is_a?(Class) && parent <= SoberSwag::InputObject
+      end
     end
   end
 end

data/lib/sober_swag/nodes/attribute.rb

@@ -2,29 +2,30 @@ module SoberSwag
   module Nodes
     ##
     # One attribute of an object.
-    class Attribute
-      def initialize(key, required, value)
+    class Attribute < Base
+      def initialize(key, required, value, meta = {})
         @key = key
         @required = required
         @value = value
+        @meta = meta
       end
 
       def deconstruct
-        [key, required, value]
+        [key, required, value, meta]
       end
 
       def deconstruct_keys
-        { key: key, required: required, value: value }
+        { key: key, required: required, value: value, meta: meta }
       end
 
-      attr_reader :key, :required, :value
+      attr_reader :key, :required, :value, :meta
 
       def map(&block)
-        self.class.new(key, required, value.map(&block))
+        self.class.new(key, required, value.map(&block), meta)
       end
 
       def cata(&block)
-        block.call(self.class.new(key, required, value.cata(&block)))
+        block.call(self.class.new(key, required, value.cata(&block), meta))
       end
     end
   end

data/lib/sober_swag/nodes/enum.rb

@@ -10,8 +10,8 @@ module SoberSwag
 
       attr_reader :values
 
-      def map(&block)
-        self.class.new(@values.map(&block))
+      def map
+        dup
       end
 
       def deconstruct

data/lib/sober_swag/nodes/primitive.rb

@@ -11,7 +11,7 @@ module SoberSwag
       attr_reader :value, :metadata
 
       def map(&block)
-        self.class.new(block.call(value))
+        self.class.new(block.call(value), metadata.dup)
       end
 
       def deconstruct

data/lib/sober_swag/output_object/definition.rb

@@ -17,8 +17,14 @@ module SoberSwag
         @fields << field
       end
 
-      def view(name, &block)
-        view = View.define(name, fields, &block)
+      def view(name, inherits: nil, &block)
+        initial_fields =
+          if inherits.nil? || inherits == :base
+            fields
+          else
+            find_view(inherits).fields
+          end
+        view = View.define(name, initial_fields, &block)
 
         view.identifier("#{@identifier}.#{name.to_s.classify}") if identifier
 
@@ -29,6 +35,12 @@ module SoberSwag
         @identifier = arg if arg
         @identifier
       end
+
+      private
+
+      def find_view(name)
+        @views.find { |view| view.name == name } || (raise ArgumentError, "no view #{name.inspect} defined!")
+      end
     end
   end
 end

data/lib/sober_swag/output_object/field_syntax.rb

@@ -7,11 +7,27 @@ module SoberSwag
         add_field!(Field.new(name, serializer, from: from, &block))
       end
 
+      ##
+      # Similar to #field, but adds multiple at once.
+      # Named #multi because #fields was already taken.
+      def multi(names, serializer)
+        names.each { |name| field(name, serializer) }
+      end
+
       ##
       # Given a symbol to this, we will use a primitive name
       def primitive(name)
         SoberSwag::Serializer.primitive(SoberSwag::Types.const_get(name))
       end
+
+      ##
+      # Merge in anything that has a list of fields, and use it.
+      # Note that merging in a full blueprint *will not* also merge in views, just fields defined on the base.
+      def merge(other)
+        other.fields.each do |field|
+          add_field!(field)
+        end
+      end
     end
   end
 end

data/lib/sober_swag/parser.rb

@@ -25,7 +25,8 @@ module SoberSwag
         Nodes::Attribute.new(
           @node.name,
           @node.required? && !@node.type.default?,
-          bind(Parser.new(@node.type))
+          bind(Parser.new(@node.type)),
+          @node.meta
         )
       when Dry::Types::Sum
         left = bind(Parser.new(@node.left))
@@ -46,14 +47,18 @@ module SoberSwag
       when Dry::Types::Constrained
         bind(Parser.new(@node.type))
       when Dry::Types::Nominal
-        old_meta = @node.primitive.respond_to?(:meta) ? @node.primitive.meta : {}
-        # start off with the moral equivalent of NodeTree[String]
-        Nodes::Primitive.new(@node.primitive, old_meta.merge(@node.meta))
+        if @node.respond_to?(:type) && @node.type.is_a?(Dry::Types::Constrained)
+          bind(Parser.new(@node.type))
+        else
+          old_meta = @node.primitive.respond_to?(:meta) ? @node.primitive.meta : {}
+          # start off with the moral equivalent of NodeTree[String]
+          Nodes::Primitive.new(@node.primitive, old_meta.merge(@node.meta))
+        end
       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
         @found.add(@node)
-        Nodes::Primitive.new(@node)
+        Nodes::Primitive.new(@node, @node.respond_to?(:meta) ? @node.meta : {})
       end
     end
 

data/lib/sober_swag/serializer/base.rb

@@ -17,6 +17,8 @@ module SoberSwag
         SoberSwag::Serializer::Optional.new(self)
       end
 
+      alias nilable optional
+
       ##
       # Is this type lazily defined?
       #

data/lib/sober_swag/serializer/meta.rb

@@ -34,7 +34,9 @@ module SoberSwag
         # As such, we need to be a bit clever about when we tack on the identifier
         # for this type.
         %i[lazy_type type].each do |sym|
-          public_send(sym).identifier(@base.public_send(sym).identifier) if @base.public_send(sym).respond_to?(:identifier)
+          if @base.public_send(sym).respond_to?(:identifier) && public_send(sym).respond_to?(:identifier)
+            public_send(sym).identifier(@base.public_send(sym).identifier)
+          end
         end
       end
 

data/lib/sober_swag/server.rb

@@ -22,28 +22,40 @@ module SoberSwag
     #
     # @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 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
@@ -53,7 +65,7 @@ module SoberSwag
       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
 

data/lib/sober_swag/type.rb

@@ -0,0 +1,7 @@
+module SoberSwag
+  ##
+  # Namespace for type-definition-related utilities
+  module Type
+    autoload(:Named, 'sober_swag/type/named')
+  end
+end

data/lib/sober_swag/type/named.rb

@@ -0,0 +1,35 @@
+module SoberSwag
+  module Type
+    ##
+    # Mixin module used to identify types that should be considered
+    # standalone, named types from SoberSwag's perspective.
+    module Named
+      ##
+      # Class Methods Module.
+      # Modules that include {SoberSwag::Type::Named}
+      # will automatically extend this module.
+      module ClassMethods
+        def alias?
+          false
+        end
+
+        def alias_of
+          nil
+        end
+
+        def root_alias
+          alias_of || self
+        end
+
+        def description(arg = nil)
+          @description = arg if arg
+          @description
+        end
+      end
+
+      def self.included(mod)
+        mod.extend(ClassMethods)
+      end
+    end
+  end
+end