apiwork 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5716ac8fad77cf2a8acaaba2580b0ce732ba68ebeefb4cf33253a436eaa6578d
-  data.tar.gz: 68225f4d7f8d5dc9826073e1d83febc94dc10b500492530a98791abc77476621
+  metadata.gz: 02f6a539dd3708f867af6e298daec039dd03bc4ea38f22e21172940332ee800f
+  data.tar.gz: a5603ca5b09b0a8baa3195629b848ceb186e3b1e1d40b987539f02195a76d76f
 SHA512:
-  metadata.gz: 94be026e4bd4260f8a69a6d8655ff4f8329aed9f4a2c1a72275e2e895c3759e873d178ce8bf3c1b0c79c5e7f1e99d1cdad8f873ca6461ed31e962abb0afe2f88
-  data.tar.gz: 6982da2ffa9df35994e22b1fcb6f238f4ab0b7a8745ad85175839a446c2842de574de9423c51bcc3e33836f898e9f549b704536893d4944ac12dd1b1710ce3a1
+  metadata.gz: 187ae2ea46e4df89ccca25bc2b88fd5a81b31f1887def0f7acfdb3dbc1fad3284f4b6f91c13956631aa20d6dd6793ac4ff1015ce36c6150c0b29dc669ca2aa18
+  data.tar.gz: 844cb5df21fe9803dabd1e450ce6a9c2f1d7f745fcb40d1d92dbfc2d95660d9ee1be719856d1b922ca5a0eeb11f8e711ce8be1eb423f20d90d348f7c55335a32

data/lib/apiwork/adapter/serializer/resource/base.rb

@@ -58,6 +58,8 @@ module Apiwork
           end
 
           def contract_types(contract_class)
+            register_representation_types(contract_class)
+
             builder_class = self.class.contract_builder
             return unless builder_class
 
@@ -77,6 +79,19 @@ module Apiwork
           def serialize(resource, context:, serialize_options:)
             raise NotImplementedError
           end
+
+          private
+
+          def register_representation_types(contract_class)
+            representation_class.type_definitions.each do |name, type_definition|
+              case type_definition[:kind]
+              when :object
+                contract_class.object(name, **type_definition[:options], &type_definition[:block])
+              when :union
+                contract_class.union(name, **type_definition[:options], &type_definition[:block])
+              end
+            end
+          end
         end
       end
     end

data/lib/apiwork/adapter/serializer/resource/default/contract_builder.rb

@@ -72,7 +72,7 @@ module Apiwork
 
                   element = attribute.element
                   if element
-                    if element.type == :array
+                    if [:array, :record].include?(element.type)
                       param_options[:of] = element.inner
                     else
                       param_options[:shape] = element.shape
@@ -95,7 +95,8 @@ module Apiwork
                   }
 
                   if association.singular?
-                    object.param(name, type: association_type || :object, **base_options)
+                    resolved_type = association_type || :object
+                    object.param(name, type: resolved_type, custom_type: association_type, **base_options)
                   elsif association.collection?
                     if association_type
                       object.param(name, type: :array, **base_options) do |param|

data/lib/apiwork/adapter/standard/capability/writing/contract_builder.rb

@@ -90,7 +90,7 @@ module Apiwork
               writable = action_name != :delete
 
               object(type_name) do |object|
-                object.literal(Constants::OP, optional: true, value: action_name.to_s)
+                object.literal(Constants::OP, value: action_name.to_s)
                 object.param(:id, optional: action_name != :delete, type: primary_key_type) unless action_name == :create
 
                 next unless writable
@@ -176,7 +176,7 @@ module Apiwork
               if attribute.element
                 element = attribute.element
 
-                if element.type == :array
+                if [:array, :record].include?(element.type)
                   options[:of] = element.inner
                 else
                   options[:shape] = element.shape

data/lib/apiwork/api/base.rb

@@ -27,6 +27,7 @@ module Apiwork
         #   @return [String]
         attr_reader :base_path,
                     :enum_registry,
+                    :explorer_config,
                     :export_configs,
                     :representation_registry,
                     :root_resource,
@@ -133,6 +134,44 @@ module Apiwork
           block.arity.positive? ? yield(@export_configs[name]) : @export_configs[name].instance_eval(&block)
         end
 
+        # @api public
+        # Configures the explorer for this API.
+        #
+        # The explorer is an interactive UI for browsing and testing API endpoints.
+        # Requires the `apiwork-explorer` gem.
+        #
+        # @yield Block evaluated in explorer context.
+        # @yieldparam explorer [Configuration]
+        # @return [void]
+        #
+        # @example Enable with defaults
+        #   explorer
+        #
+        # @example Custom configuration
+        #   explorer do
+        #     mode :always
+        #     path '/explorer'
+        #   end
+        def explorer(&block)
+          unless defined?(Apiwork::Explorer::Engine)
+            raise ConfigurationError,
+                  'explorer requires the apiwork-explorer gem. ' \
+                  "Add it to your Gemfile: gem 'apiwork-explorer'"
+          end
+
+          unless @explorer_config
+            options = Configurable.define do
+              option :mode, default: :auto, enum: %i[auto always never], type: :symbol
+              option :path, default: '/.explorer', type: :string
+            end
+            @explorer_config = Configuration.new(options)
+          end
+
+          return @explorer_config unless block
+
+          block.arity.positive? ? yield(@explorer_config) : @explorer_config.instance_eval(&block)
+        end
+
         # @api public
         # Sets or configures the adapter for this API.
         #
@@ -644,6 +683,7 @@ module Apiwork
           @info = nil
           @locales = []
           @raises = []
+          @explorer_config = nil
           @export_configs = {}
           @adapter_config = nil
           @root_resource = Resource.new(self)
@@ -682,16 +722,33 @@ module Apiwork
           end.join('/')
         end
 
+        def transform_key(key)
+          key_string = key.to_s
+
+          return key_string if key_string.match?(/\A[A-Z]+\z/)
+
+          case key_format
+          when :camel then key_string.camelize(:lower)
+          when :pascal then key_string.camelize
+          when :kebab then key_string.dasherize
+          when :underscore then key_string.underscore
+          else key_string
+          end
+        end
+
+        def normalize_key(key)
+          key_string = key.to_s
+
+          return key_string if key_string.match?(/\A[A-Z]+\z/)
+
+          key_string.underscore
+        end
+
         def normalize_request(request)
-          return request if %i[camel pascal kebab].exclude?(key_format)
+          return request if key_format == :keep
 
           request.transform do |hash|
-            hash.deep_transform_keys do |key|
-              key_string = key.to_s
-              next key if key_string.match?(/\A[A-Z]+\z/)
-
-              key_string.underscore.to_sym
-            end
+            hash.deep_transform_keys { |key| normalize_key(key).to_sym }
           end
         end
 
@@ -701,16 +758,9 @@ module Apiwork
 
         def prepare_response(response)
           result = adapter.apply_response_transformers(response)
-          case key_format
-          when :camel
-            result.transform { |hash| hash.deep_transform_keys { |key| key.to_s.camelize(:lower).to_sym } }
-          when :pascal
-            result.transform { |hash| hash.deep_transform_keys { |key| key.to_s.camelize.to_sym } }
-          when :kebab
-            result.transform { |hash| hash.deep_transform_keys { |key| key.to_s.dasherize.to_sym } }
-          else
-            result
-          end
+          return result if key_format == :keep
+
+          result.transform { |hash| hash.deep_transform_keys { |key| transform_key(key).to_sym } }
         end
 
         def type?(name, scope: nil)

data/lib/apiwork/api/element.rb

@@ -32,7 +32,7 @@ module Apiwork
       # This is the verbose form. Prefer sugar methods (string, integer, etc.)
       # for static definitions. Use `of` for dynamic element generation.
       #
-      # @param type [Symbol] [:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :literal, :number, :object, :string, :time, :union, :uuid]
+      # @param type [Symbol] [:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :literal, :number, :object, :string, :time, :union, :unknown, :uuid]
       #   The element type. Custom type references are also allowed.
       # @param discriminator [Symbol, nil] (nil)
       #   The discriminator field name. Unions only.
@@ -64,9 +64,25 @@ module Apiwork
       #       string :name
       #     end
       #   end
+      #
+      # @example Discriminated union
+      #   array :payments do
+      #     of :union, discriminator: :type do
+      #       variant tag: 'card' do
+      #         object do
+      #           string :last_four
+      #         end
+      #       end
+      #       variant tag: 'bank' do
+      #         object do
+      #           string :account_number
+      #         end
+      #       end
+      #     end
+      #   end
       def of(type, discriminator: nil, enum: nil, format: nil, max: nil, min: nil, value: nil, &block)
         case type
-        when :string, :integer, :decimal, :boolean, :number, :datetime, :date, :uuid, :time, :binary
+        when :string, :integer, :decimal, :boolean, :number, :datetime, :date, :uuid, :time, :binary, :unknown
           set_type(type, enum:, format:, max:, min:)
         when :literal
           @type = :literal
@@ -90,6 +106,15 @@ module Apiwork
           @inner = inner
           @shape = inner.shape
           @defined = true
+        when :record
+          raise ConfigurationError, 'record requires a block' unless block
+
+          inner = Element.new
+          block.arity.positive? ? yield(inner) : inner.instance_eval(&block)
+          inner.validate!
+          @type = :record
+          @inner = inner
+          @defined = true
         when :union
           raise ConfigurationError, 'union requires a block' unless block
 
@@ -105,6 +130,12 @@ module Apiwork
           @defined = true
         end
       end
+
+      def reference(type_name)
+        @type = type_name
+        @custom_type = type_name
+        @defined = true
+      end
     end
   end
 end

data/lib/apiwork/api/object.rb

@@ -7,7 +7,7 @@ module Apiwork
     #
     # Accessed via `object :name do` in API or contract definitions.
     # Use type methods to define params: {#string}, {#integer}, {#decimal},
-    # {#boolean}, {#array}, {#object}, {#union}, {#reference}.
+    # {#boolean}, {#array}, {#record}, {#object}, {#union}, {#reference}.
     #
     # @see API::Element Block context for array/variant elements
     # @see Contract::Object Block context for inline objects
@@ -32,7 +32,7 @@ module Apiwork
       #
       # @param name [Symbol]
       #   The param name.
-      # @param type [Symbol, nil] (nil) [:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :literal, :number, :object, :string, :time, :union, :uuid]
+      # @param type [Symbol, nil] (nil) [:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :literal, :number, :object, :record, :string, :time, :union, :unknown, :uuid]
       #   The param type.
       # @param as [Symbol, nil] (nil)
       #   The target attribute name.
@@ -59,7 +59,7 @@ module Apiwork
       # @param nullable [Boolean] (false)
       #   Whether the value can be `null`.
       # @param of [Symbol, Hash, nil] (nil)
-      #   The element type. Arrays only.
+      #   The element or value type. Arrays and records only.
       # @param optional [Boolean] (false)
       #   Whether the param is optional.
       # @param required [Boolean] (false)
@@ -85,6 +85,7 @@ module Apiwork
         name,
         type: nil,
         as: nil,
+        custom_type: nil,
         default: nil,
         deprecated: false,
         description: nil,
@@ -103,11 +104,12 @@ module Apiwork
         &block
       )
         resolved_of = resolve_of(of, type, &block)
-        resolved_shape = type == :array ? nil : (shape || build_shape(type, discriminator, &block))
+        resolved_shape = [:array, :record].include?(type) ? nil : (shape || build_shape(type, discriminator, &block))
         discriminator = resolved_of&.discriminator if type == :array
 
         param_hash = {
           as:,
+          custom_type:,
           default:,
           deprecated:,
           description:,
@@ -193,10 +195,73 @@ module Apiwork
         )
       end
 
+      # @api public
+      # Defines a record param with value type.
+      #
+      # @param name [Symbol]
+      #   The param name.
+      # @param as [Symbol, nil] (nil)
+      #   The target attribute name.
+      # @param default [Object, nil] (nil)
+      #   The default value.
+      # @param deprecated [Boolean] (false)
+      #   Whether deprecated. Metadata included in exports.
+      # @param description [String, nil] (nil)
+      #   The description. Metadata included in exports.
+      # @param nullable [Boolean] (false)
+      #   Whether the value can be `null`.
+      # @param optional [Boolean] (false)
+      #   Whether the param is optional.
+      # @param required [Boolean] (false)
+      #   Whether the param is required.
+      # @yield block for defining value type
+      # @yieldparam element [API::Element]
+      # @return [void]
+      #
+      # @example instance_eval style
+      #   record :scores do
+      #     integer
+      #   end
+      #
+      # @example yield style
+      #   record :scores do |element|
+      #     element.integer
+      #   end
+      def record(
+        name,
+        as: nil,
+        default: nil,
+        deprecated: false,
+        description: nil,
+        nullable: false,
+        optional: false,
+        required: false,
+        &block
+      )
+        raise ArgumentError, 'record requires a block' unless block
+
+        element = Element.new
+        block.arity.positive? ? yield(element) : element.instance_eval(&block)
+        element.validate!
+
+        param(
+          name,
+          as:,
+          default:,
+          deprecated:,
+          description:,
+          nullable:,
+          optional:,
+          required:,
+          of: element,
+          type: :record,
+        )
+      end
+
       private
 
       def resolve_of(of, type, &block)
-        return nil unless type == :array
+        return nil unless [:array, :record].include?(type)
 
         if block
           element = Element.new

data/lib/apiwork/api/router.rb

@@ -35,6 +35,22 @@ module Apiwork
               end
             end
 
+            if api_class.explorer_config && defined?(Apiwork::Explorer::Engine)
+              mount_explorer = case api_class.explorer_config.mode
+                               when :always then true
+                               when :never then false
+                               when :auto then Rails.env.development?
+                               end
+
+              if mount_explorer
+                scope path: api_class.transform_path(api_class.base_path) do
+                  mount Apiwork::Explorer::Engine,
+                        at: api_class.explorer_config.path,
+                        defaults: { api_base_path: api_class.base_path }
+                end
+              end
+            end
+
             scope module: api_class.namespaces.map(&:to_s).join('/').underscore,
                   path: api_class.transform_path(api_class.base_path) do
               router.draw_resources(self, api_class.root_resource.resources, api_class)

data/lib/apiwork/configuration/validatable.rb

@@ -7,6 +7,7 @@ module Apiwork
 
       def validate_type!(value)
         valid = case type
+                when :boolean then value.is_a?(TrueClass) || value.is_a?(FalseClass)
                 when :symbol then value.is_a?(Symbol)
                 when :string then value.is_a?(String)
                 when :integer then value.is_a?(Integer)

data/lib/apiwork/configuration.rb

@@ -24,6 +24,8 @@ module Apiwork
       raise ConfigurationError, "Unknown option: #{name}" unless option
 
       if args.empty? && !block
+        return @storage[name] = true if option.type == :boolean
+
         stored = @storage[name]
 
         if option.nested?

data/lib/apiwork/contract/element.rb

@@ -37,7 +37,7 @@ module Apiwork
       # This is the verbose form. Prefer sugar methods (string, integer, etc.)
       # for static definitions. Use `of` for dynamic element generation.
       #
-      # @param type [Symbol] [:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :literal, :number, :object, :string, :time, :union, :uuid]
+      # @param type [Symbol] [:array, :binary, :boolean, :date, :datetime, :decimal, :integer, :literal, :number, :object, :string, :time, :union, :unknown, :uuid]
       #   The element type. Custom type references are also allowed.
       # @param discriminator [Symbol, nil] (nil)
       #   The discriminator field name. Unions only.
@@ -75,7 +75,7 @@ module Apiwork
         resolved_enum = enum.is_a?(Symbol) ? resolve_enum(enum) : enum
 
         case type
-        when :string, :integer, :decimal, :boolean, :number, :datetime, :date, :uuid, :time, :binary
+        when :string, :integer, :decimal, :boolean, :number, :datetime, :date, :uuid, :time, :binary, :unknown
           set_type(type, format:, max:, min:, enum: resolved_enum)
         when :literal
           @type = :literal
@@ -99,6 +99,15 @@ module Apiwork
           @inner = inner
           @shape = inner.shape
           @defined = true
+        when :record
+          raise ConfigurationError, 'record requires a block' unless block
+
+          inner = Element.new(@contract_class)
+          block.arity.positive? ? yield(inner) : inner.instance_eval(&block)
+          inner.validate!
+          @type = :record
+          @inner = inner
+          @defined = true
         when :union
           raise ConfigurationError, 'union requires a block' unless block
 
@@ -115,6 +124,12 @@ module Apiwork
         end
       end
 
+      def reference(type_name)
+        @type = type_name
+        @custom_type = type_name
+        @defined = true
+      end
+
       private
 
       def resolve_enum(enum)

data/lib/apiwork/contract/object/coercer.rb

@@ -85,6 +85,7 @@ module Apiwork
 
           return coerce_union(value, param_options[:union]) if type == :union
           return coerce_array(value, param_options) if type == :array && value.is_a?(Array)
+          return coerce_record(value, param_options) if type == :record && value.is_a?(Hash)
           return Coercer.coerce(param_options[:shape], value) if param_options[:shape] && value.is_a?(Hash)
 
           if value.is_a?(Hash) && type && !PRIMITIVES.key?(type)
@@ -105,7 +106,9 @@ module Apiwork
           custom_shape = resolve_custom_shape(of_type) if of_type && !PRIMITIVES.key?(of_type)
 
           array.map do |item|
-            if of_shape && item.is_a?(Hash)
+            if of_type == :union && item.is_a?(Hash)
+              coerce_union(item, of_shape)
+            elsif of_shape && item.is_a?(Hash)
               Coercer.coerce(of_shape, item)
             elsif of_type && PRIMITIVES.key?(of_type)
               coerced = coerce_primitive(item, of_type)
@@ -120,6 +123,23 @@ module Apiwork
           end
         end
 
+        def coerce_record(hash, param_options)
+          of = param_options[:of]
+          of_type = of&.type
+          of_shape = of&.shape
+
+          hash.transform_values do |item|
+            if of_shape && item.is_a?(Hash)
+              Coercer.coerce(of_shape, item)
+            elsif of_type && PRIMITIVES.key?(of_type)
+              coerced = coerce_primitive(item, of_type)
+              coerced.nil? ? item : coerced
+            else
+              item
+            end
+          end
+        end
+
         def coerce_union(value, union)
           if union.variants.any? { |variant| variant[:type] == :boolean }
             coerced = coerce_primitive(value, :boolean)
@@ -191,7 +211,9 @@ module Apiwork
           type_definition = @shape.contract_class.resolve_custom_type(type_name)
           return @type_cache[type_name] = nil unless type_definition
 
-          @type_cache[type_name] = Object.new(@shape.contract_class).tap do |type_shape|
+          scope = type_definition.scope || @shape.contract_class
+
+          @type_cache[type_name] = Object.new(scope).tap do |type_shape|
             type_shape.copy_type_definition_params(type_definition, type_shape)
           end
         end

data/lib/apiwork/contract/object/deserializer.rb

@@ -85,10 +85,14 @@ module Apiwork
         end
 
         def deserialize_array(array, param_options)
+          of = param_options[:of]
+
           array.map do |item|
             next item unless item.is_a?(Hash)
 
-            if param_options[:shape]
+            if of&.type == :union && of.shape.is_a?(Apiwork::Union)
+              deserialize_union(item, of.shape)
+            elsif param_options[:shape]
               Deserializer.deserialize(param_options[:shape], item)
             else
               item

data/lib/apiwork/contract/object/transformer.rb

@@ -32,11 +32,22 @@ module Apiwork
 
             if param_options[:shape] && value.is_a?(Hash)
               transformed[name] = Transformer.transform(param_options[:shape], value)
-            elsif param_options[:type] == :array && value.is_a?(Array)
+            elsif param_options[:type] == :record && value.is_a?(Hash)
               of = param_options[:of]
               of_shape = of&.shape
 
               if of_shape
+                transformed[name] = value.transform_values do |item|
+                  item.is_a?(Hash) ? Transformer.transform(of_shape, item) : item
+                end
+              end
+            elsif param_options[:type] == :array && value.is_a?(Array)
+              of = param_options[:of]
+              of_shape = of&.shape
+
+              if of&.type == :union
+                transformed[name] = value
+              elsif of_shape
                 transformed[name] = value.map do |item|
                   item.is_a?(Hash) ? Transformer.transform(of_shape, item) : item
                 end
@@ -85,7 +96,9 @@ module Apiwork
         end
 
         def build_type_shape(type_definition, contract_class)
-          type_shape = Object.new(contract_class, action_name: @shape.action_name)
+          scope = type_definition.scope || contract_class
+
+          type_shape = Object.new(scope, action_name: @shape.action_name)
           type_shape.copy_type_definition_params(type_definition, type_shape)
           type_shape
         end

data/lib/apiwork/contract/object/validator.rb

@@ -201,6 +201,8 @@ module Apiwork
             validate_shape_object(value, param_options[:shape], field_path, max_depth, current_depth)
           elsif param_options[:type] == :array && value.is_a?(Array)
             validate_array_param(value, param_options, field_path, max_depth, current_depth)
+          elsif param_options[:type] == :record && value.is_a?(Hash)
+            validate_record_param(value, param_options, field_path, max_depth, current_depth)
           else
             [[], value]
           end
@@ -230,6 +232,41 @@ module Apiwork
           array_issues.empty? ? [[], array_values] : [array_issues, NOT_SET]
         end
 
+        def validate_record_param(value, param_options, field_path, max_depth, current_depth)
+          issues = []
+          validated = {}
+
+          of = param_options[:of]
+          of_type = of&.type
+          of_shape = of&.shape
+
+          value.each do |key, item|
+            item_path = field_path + [key]
+
+            if of_shape
+              validator = Validator.new(normalize_shape(of_shape))
+              shape_result = validator.validate(
+                item,
+                max_depth:,
+                current_depth: current_depth + 1,
+                path: item_path,
+              )
+              if shape_result.invalid?
+                issues.concat(shape_result.issues)
+              else
+                validated[key] = shape_result.params
+              end
+            elsif of_type
+              type_error = validate_type(key, item, of_type, item_path)
+              type_error ? issues << type_error : validated[key] = item
+            else
+              validated[key] = item
+            end
+          end
+
+          issues.empty? ? [[], validated] : [issues, NOT_SET]
+        end
+
         def check_unknown_params(data, path)
           extra_keys = data.keys - @shape.params.keys
           extra_keys.map do |key|
@@ -280,7 +317,10 @@ module Apiwork
           array.each_with_index do |item, index|
             item_path = field_path + [index]
 
-            if of_shape
+            if of&.type == :union && of_shape.is_a?(Apiwork::Union)
+              error, validated = validate_union(nil, item, of_shape, item_path, current_depth:, max_depth:)
+              error ? issues << error : values << validated
+            elsif of_shape
               validator = Validator.new(normalize_shape(of_shape))
               shape_result = validator.validate(
                 item,
@@ -369,6 +409,7 @@ module Apiwork
                   when :uuid then value.is_a?(String) && value.match?(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i)
                   when :object then value.is_a?(Hash)
                   when :array then value.is_a?(Array)
+                  when :record then value.is_a?(Hash)
                   when :decimal, :number then value.is_a?(Numeric)
                   else true
                   end
@@ -600,7 +641,9 @@ module Apiwork
         end
 
         def validate_with_type_definition(type_definition, value, path, current_depth:, exclude_param: nil, max_depth:)
-          type_shape = Object.new(@shape.contract_class, action_name: @shape.action_name)
+          scope = type_definition.scope || @shape.contract_class
+
+          type_shape = Object.new(scope, action_name: @shape.action_name)
           type_shape.copy_type_definition_params(type_definition, type_shape)
           type_shape.params.delete(exclude_param) if exclude_param