apiwork 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61f7ef3c54d36ed6bced4d7e84233b2ab4879c697a29468202c09b811074e2f6
-  data.tar.gz: 0b285cc8cd1b5e5ad64b85d8e1bbe17cb82d281b2b69bf7b51a5468db2a9e43a
+  metadata.gz: 02f6a539dd3708f867af6e298daec039dd03bc4ea38f22e21172940332ee800f
+  data.tar.gz: a5603ca5b09b0a8baa3195629b848ceb186e3b1e1d40b987539f02195a76d76f
 SHA512:
-  metadata.gz: 31a41407721690942c50e1db93d5e602e67ee4dde083ff3e44b3a86e4935f874463856ee0217306156d4c7e29c994c46c9a21da9b185b9c6477a0b96b71aa6bd
-  data.tar.gz: 4e197e9a7d1301ca771867b0ab85a777fdf0ab1e2951871ec156370f8118805cf0c502c65da8e6ed629d52eaab4ea8c7222639d2a6f0802077d401bb6c49588a
+  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

@@ -15,7 +15,7 @@ module Apiwork
               if sti_base_representation?
                 build_sti_response_union_type
               else
-                register_type(representation_class.root_key.singular.to_sym) unless type?(scoped_type_name(nil))
+                register_type(representation_class.root_key.singular.to_sym)
 
                 scoped_type_name(nil)
               end
@@ -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

@@ -8,12 +8,13 @@ module Apiwork
           class ContractBuilder < Adapter::Capability::Contract::Base
             def build
               build_enums
-              build_payload_types
               build_nested_payload_union if api_class.representation_registry.nested_writable?(representation_class)
 
               %i[create update].each do |action_name|
                 next unless scope.action?(action_name)
 
+                build_payload_type(action_name)
+
                 payload_type_name = [action_name, 'payload'].join('_').to_sym
                 next unless type?(payload_type_name)
 
@@ -26,6 +27,11 @@ module Apiwork
                   end
                 end
               end
+
+              return unless representation_class.subclass?
+
+              build_payload_type(:create)
+              build_payload_type(:update)
             end
 
             private
@@ -38,11 +44,6 @@ module Apiwork
               end
             end
 
-            def build_payload_types
-              build_payload_type(:create)
-              build_payload_type(:update)
-            end
-
             def build_payload_type(action_name)
               if sti_base_representation?
                 build_sti_payload_union(action_name)
@@ -55,6 +56,9 @@ module Apiwork
               type_name = [action_name, 'payload'].join('_').to_sym
               return if type?(type_name)
 
+              writable_params = collect_writable_params(action_name)
+              return if writable_params.empty? && !representation_class.subclass?
+
               object(type_name, description: representation_class.description) do |object|
                 if representation_class.subclass?
                   parent_inheritance = representation_class.superclass.inheritance
@@ -66,7 +70,7 @@ module Apiwork
                   )
                 end
 
-                collect_writable_params(action_name).each do |param_config|
+                writable_params.each do |param_config|
                   object.param(param_config[:name], **param_config[:options])
                 end
               end
@@ -86,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
@@ -172,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.
         #
@@ -276,6 +315,30 @@ module Apiwork
           register_union(name, deprecated:, description:, discriminator:, example:, &block)
         end
 
+        # @api public
+        # Supported locales for this API.
+        #
+        # Declares which locales this API supports. Used by introspection
+        # to validate locale parameters and included in introspection output.
+        #
+        # @param locale_keys [Array<Symbol>]
+        #   The locale identifiers.
+        # @return [Array<Symbol>]
+        # @raise [ConfigurationError] if any locale is not a Symbol
+        #
+        # @example
+        #   locales :en, :sv, :it
+        #   api_class.locales # => [:en, :sv, :it]
+        def locales(*locale_keys)
+          return @locales if locale_keys.empty?
+
+          locale_keys = locale_keys.flatten.uniq
+          locale_keys.each do |locale_key|
+            raise ConfigurationError, "locales must be symbols, got #{locale_key.class}: #{locale_key}" unless locale_key.is_a?(Symbol)
+          end
+          @locales = locale_keys
+        end
+
         # @api public
         # API-wide error codes.
         #
@@ -534,6 +597,18 @@ module Apiwork
           @root_resource.with_options(options, &block)
         end
 
+        # @api public
+        # The fingerprint for this API.
+        #
+        # A 16-character hex digest derived from the application name and {.base_path}.
+        #
+        # @return [String]
+        def fingerprint
+          @fingerprint ||= Digest::SHA256.hexdigest(
+            [Rails.application.class.module_parent_name, base_path].join(':'),
+          )[0, 16]
+        end
+
         def register_object(name, deprecated: false, description: nil, example: nil, scope: nil, &block)
           type_registry.register(
             name,
@@ -602,10 +677,13 @@ module Apiwork
 
         def mount(base_path)
           @base_path = base_path
+          @fingerprint = nil
           @locale_key = nil
           @namespaces = nil
           @info = nil
+          @locales = []
           @raises = []
+          @explorer_config = nil
           @export_configs = {}
           @adapter_config = nil
           @root_resource = Resource.new(self)
@@ -644,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
 
@@ -663,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,16 +32,16 @@ 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.
       # @param enum [Array, Symbol, nil] (nil)
       #   The allowed values. Strings and integers only.
-      # @param format [Symbol, nil] (nil) [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :url, :uuid]
+      # @param format [Symbol, nil] (nil) [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :text, :url, :uuid]
       #   Format hint for exports. Does not change the type, but exports may add validation or documentation based on it.
       #   Valid formats by type: `:decimal`/`:number` (`:double`, `:float`), `:integer` (`:int32`, `:int64`),
-      #   `:string` (`:date`, `:datetime`, `:email`, `:hostname`, `:ipv4`, `:ipv6`, `:password`, `:url`, `:uuid`).
+      #   `:string` (`:date`, `:datetime`, `:email`, `:hostname`, `:ipv4`, `:ipv6`, `:password`, `:text`, `:url`, `:uuid`).
       # @param max [Integer, nil] (nil)
       #   The maximum. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.
       # @param min [Integer, nil] (nil)
@@ -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.
@@ -48,10 +48,10 @@ module Apiwork
       #   The allowed values.
       # @param example [Object, nil] (nil)
       #   The example value. Metadata included in exports.
-      # @param format [Symbol, nil] (nil) [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :url, :uuid]
+      # @param format [Symbol, nil] (nil) [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :text, :url, :uuid]
       #   Format hint for exports. Does not change the type, but exports may add validation or documentation based on it.
       #   Valid formats by type: `:decimal`/`:number` (`:double`, `:float`), `:integer` (`:int32`, `:int64`),
-      #   `:string` (`:date`, `:datetime`, `:email`, `:hostname`, `:ipv4`, `:ipv6`, `:password`, `:url`, `:uuid`).
+      #   `:string` (`:date`, `:datetime`, `:email`, `:hostname`, `:ipv4`, `:ipv6`, `:password`, `:text`, `:url`, `:uuid`).
       # @param max [Integer, nil] (nil)
       #   The maximum. For `:array`: size. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.
       # @param min [Integer, nil] (nil)
@@ -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,16 +37,16 @@ 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.
       # @param enum [Array, Symbol, nil] (nil)
       #   The allowed values or enum reference. Strings and integers only.
-      # @param format [Symbol, nil] (nil) [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :url, :uuid]
+      # @param format [Symbol, nil] (nil) [:date, :datetime, :double, :email, :float, :hostname, :int32, :int64, :ipv4, :ipv6, :password, :text, :url, :uuid]
       #   Format hint for exports. Does not change the type, but exports may add validation or documentation based on it.
       #   Valid formats by type: `:decimal`/`:number` (`:double`, `:float`), `:integer` (`:int32`, `:int64`),
-      #   `:string` (`:date`, `:datetime`, `:email`, `:hostname`, `:ipv4`, `:ipv6`, `:password`, `:url`, `:uuid`).
+      #   `:string` (`:date`, `:datetime`, `:email`, `:hostname`, `:ipv4`, `:ipv6`, `:password`, `:text`, `:url`, `:uuid`).
       # @param max [Integer, nil] (nil)
       #   The maximum. For `:decimal`, `:integer`, `:number`: value. For `:string`: length.
       # @param min [Integer, nil] (nil)
@@ -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)