apiwork 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61f7ef3c54d36ed6bced4d7e84233b2ab4879c697a29468202c09b811074e2f6
-  data.tar.gz: 0b285cc8cd1b5e5ad64b85d8e1bbe17cb82d281b2b69bf7b51a5468db2a9e43a
+  metadata.gz: 5716ac8fad77cf2a8acaaba2580b0ce732ba68ebeefb4cf33253a436eaa6578d
+  data.tar.gz: 68225f4d7f8d5dc9826073e1d83febc94dc10b500492530a98791abc77476621
 SHA512:
-  metadata.gz: 31a41407721690942c50e1db93d5e602e67ee4dde083ff3e44b3a86e4935f874463856ee0217306156d4c7e29c994c46c9a21da9b185b9c6477a0b96b71aa6bd
-  data.tar.gz: 4e197e9a7d1301ca771867b0ab85a777fdf0ab1e2951871ec156370f8118805cf0c502c65da8e6ed629d52eaab4ea8c7222639d2a6f0802077d401bb6c49588a
+  metadata.gz: 94be026e4bd4260f8a69a6d8655ff4f8329aed9f4a2c1a72275e2e895c3759e873d178ce8bf3c1b0c79c5e7f1e99d1cdad8f873ca6461ed31e962abb0afe2f88
+  data.tar.gz: 6982da2ffa9df35994e22b1fcb6f238f4ab0b7a8745ad85175839a446c2842de574de9423c51bcc3e33836f898e9f549b704536893d4944ac12dd1b1710ce3a1

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

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

data/lib/apiwork/api/base.rb

@@ -276,6 +276,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 +558,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,9 +638,11 @@ module Apiwork
 
         def mount(base_path)
           @base_path = base_path
+          @fingerprint = nil
           @locale_key = nil
           @namespaces = nil
           @info = nil
+          @locales = []
           @raises = []
           @export_configs = {}
           @adapter_config = nil

data/lib/apiwork/api/element.rb

@@ -38,10 +38,10 @@ module Apiwork
       #   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)

data/lib/apiwork/api/object.rb

@@ -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)

data/lib/apiwork/contract/element.rb

@@ -43,10 +43,10 @@ module Apiwork
       #   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)

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

@@ -156,6 +156,13 @@ module Apiwork
 
             next if discriminator
 
+            if PRIMITIVES.key?(variant_type) && !value.is_a?(Hash) && !value.is_a?(Array)
+              coerced = coerce_primitive(value, variant_type)
+              return coerced unless coerced.nil?
+
+              next
+            end
+
             custom_shape = resolve_custom_shape(variant_type)
             next unless custom_shape
 

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

@@ -129,14 +129,7 @@ module Apiwork
           return nil if param_options[:optional]
           return nil if param_options[:nullable] && data.key?(name) && value.nil?
 
-          missing = case param_options[:type]
-                    when :boolean, :string
-                      value.nil?
-                    else
-                      value.blank?
-                    end
-
-          return nil unless missing
+          return nil unless value.nil?
 
           if param_options[:enum].present?
             Issue.new(
@@ -437,6 +430,8 @@ module Apiwork
               most_specific_error = error
             elsif error.code == :value_invalid && (most_specific_error.nil? || most_specific_error.code != :field_unknown)
               most_specific_error = error
+            elsif error.path.length > path.length && most_specific_error.nil?
+              most_specific_error = error
             end
           end
 
@@ -448,7 +443,7 @@ module Apiwork
             translate_detail(:type_invalid),
             path:,
             meta: {
-              actual: value.is_a?(Hash) ? :hash : value.class.name.underscore.to_sym,
+              actual: value.is_a?(Hash) ? :object : value.class.name.underscore.to_sym,
               expected: expected_types.join(' | '),
               field: name,
             },

data/lib/apiwork/contract/object.rb

@@ -72,10 +72,10 @@ module Apiwork
       #   The allowed values or enum reference.
       # @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)

data/lib/apiwork/element.rb

@@ -82,7 +82,7 @@ module Apiwork
     #
     # @param enum [Array, Symbol, nil] (nil)
     #   The allowed values.
-    # @param format [Symbol, nil] (nil) [:date, :datetime, :email, :hostname, :ipv4, :ipv6, :password, :url, :uuid]
+    # @param format [Symbol, nil] (nil) [:date, :datetime, :email, :hostname, :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: `:string`.
     # @param max [Integer, nil] (nil)

data/lib/apiwork/introspection/api.rb

@@ -33,6 +33,14 @@ module Apiwork
         @dump[:base_path]
       end
 
+      # @api public
+      # The fingerprint for this API.
+      #
+      # @return [String]
+      def fingerprint
+        @dump[:fingerprint]
+      end
+
       # @api public
       # The info for this API.
       #
@@ -65,6 +73,14 @@ module Apiwork
         @enums ||= @dump[:enums].transform_values { |dump| Enum.new(dump) }
       end
 
+      # @api public
+      # The supported locales for this API.
+      #
+      # @return [Array<Symbol>]
+      def locales
+        @dump[:locales]
+      end
+
       # @api public
       # The error codes for this API.
       #
@@ -80,6 +96,8 @@ module Apiwork
       def to_h
         {
           base_path:,
+          fingerprint:,
+          locales:,
           enums: enums.transform_values(&:to_h),
           error_codes: error_codes.transform_values(&:to_h),
           info: info&.to_h,

data/lib/apiwork/introspection/dump/api.rb

@@ -18,7 +18,9 @@ module Apiwork
             base_path: @api_class.transform_path(@api_class.base_path),
             enums: type_dump_hash[:enums],
             error_codes: build_error_codes(collect_all_error_code_keys(resources)),
+            fingerprint: @api_class.fingerprint,
             info: build_info,
+            locales: @api_class.locales,
             types: type_dump_hash[:types],
           }
         end

data/lib/apiwork/introspection/dump/resource.rb

@@ -4,11 +4,12 @@ module Apiwork
   module Introspection
     module Dump
       class Resource
-        def initialize(resource, api_class, parent_identifiers: [], parent_param: nil, parent_singular: false)
+        def initialize(resource, api_class, parent_identifiers: [], parent_param: nil, parent_path: nil, parent_singular: false)
           @resource = resource
           @api_class = api_class
           @parent_identifiers = parent_identifiers
           @parent_param = parent_param
+          @parent_path = parent_path
           @parent_singular = parent_singular
         end
 
@@ -57,10 +58,11 @@ module Apiwork
         end
 
         def build_resource_path(formatted_segment)
-          return formatted_segment if @parent_identifiers.empty?
-          return formatted_segment if @parent_singular
+          return formatted_segment if @parent_path.nil?
+          return "#{@parent_path}/#{formatted_segment}" if @parent_singular
 
-          ":#{@parent_param || "#{@parent_identifiers.last.singularize}_id"}/#{formatted_segment}"
+          param = @parent_param || "#{@parent_identifiers.last.singularize}_id"
+          "#{@parent_path}/:#{param}/#{formatted_segment}"
         end
 
         def build_nested_resources(resource_path)
@@ -70,6 +72,7 @@ module Apiwork
 
           nested_options = {
             parent_identifiers: child_parent_identifiers,
+            parent_path: resource_path,
             parent_singular: @resource.singular,
           }
           nested_options[:parent_param] = @resource.param&.to_s || "#{@resource.name.to_s.singularize}_id" unless @resource.singular

data/lib/apiwork/introspection/param/base.rb

@@ -64,14 +64,6 @@ module Apiwork
           @dump[:default]
         end
 
-        # @api public
-        # Whether this param has a default.
-        #
-        # @return [Boolean]
-        def default?
-          @dump.key?(:default)
-        end
-
         # @api public
         # The tag for this param.
         #

data/lib/apiwork/introspection.rb

@@ -4,23 +4,36 @@ module Apiwork
   module Introspection
     class << self
       def api(api_class, locale: nil)
+        validate_locale(api_class, locale)
         with_locale(locale) { API.new(Dump.api(api_class)) }
       end
 
       def contract(contract_class, expand: false, locale: nil)
+        validate_locale(contract_class.api_class, locale)
         with_locale(locale) { Contract.new(Dump.contract(contract_class, expand:)) }
       end
 
       private
 
-      def with_locale(locale, &block)
-        return yield unless locale
+      def validate_locale(api_class, locale)
+        return unless locale
+        return unless api_class
 
-        unless I18n.available_locales.include?(locale)
+        if api_class.locales.empty?
           raise ConfigurationError,
-                "locale must be one of #{I18n.available_locales.inspect}, got #{locale.inspect}"
+                "locale :#{locale} was requested but no locales are defined. " \
+                "Add `locales #{locale.inspect}` to your API definition."
         end
 
+        return if api_class.locales.include?(locale)
+
+        raise ConfigurationError,
+              "locale must be one of #{api_class.locales.inspect}, got #{locale.inspect}"
+      end
+
+      def with_locale(locale, &block)
+        return yield unless locale
+
         I18n.with_locale(locale, &block)
       end
     end

data/lib/apiwork/object.rb

@@ -71,7 +71,7 @@ module Apiwork
     #   The allowed values.
     # @param example [String, nil] (nil)
     #   The example value. Metadata included in exports.
-    # @param format [Symbol, nil] (nil) [:date, :datetime, :email, :hostname, :ipv4, :ipv6, :password, :url, :uuid]
+    # @param format [Symbol, nil] (nil) [:date, :datetime, :email, :hostname, :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: `:string`.
     # @param max [Integer, nil] (nil)
@@ -144,7 +144,7 @@ module Apiwork
     #   The allowed values.
     # @param example [String, nil] (nil)
     #   The example value. Metadata included in exports.
-    # @param format [Symbol, nil] (nil) [:date, :datetime, :email, :hostname, :ipv4, :ipv6, :password, :url, :uuid]
+    # @param format [Symbol, nil] (nil) [:date, :datetime, :email, :hostname, :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: `:string`.
     # @param max [Integer, nil] (nil)

data/lib/apiwork/representation/attribute.rb

@@ -18,7 +18,7 @@ module Apiwork
         decimal: %i[float double],
         integer: %i[int32 int64],
         number: %i[float double],
-        string: %i[email uuid url date datetime ipv4 ipv6 password hostname],
+        string: %i[date datetime email hostname ipv4 ipv6 password text url uuid],
       }.freeze
 
       # @!attribute [r] description

data/lib/apiwork/representation/base.rb

@@ -197,11 +197,11 @@ module Apiwork
         #   The example. Metadata included in exports.
         # @param filterable [Boolean] (false)
         #   Whether the attribute is filterable.
-        # @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`).
+        #   `: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)

data/lib/apiwork/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Apiwork
-  VERSION = '0.3.1'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apiwork
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - skiftle
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-04 00:00:00.000000000 Z
+date: 2026-03-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement