apiwork 0.4.0 → 0.6.0

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

@@ -25,6 +25,22 @@ module Apiwork
       #     param.enum_reference? # => false
       #   end
       class Integer < Base
+        # @api public
+        # The default for this param.
+        #
+        # @return [Object, nil]
+        def default
+          @dump[:default]
+        end
+
+        # @api public
+        # The example for this param.
+        #
+        # @return [Object, nil]
+        def example
+          @dump[:example]
+        end
+
         # @api public
         # The minimum for this param.
         #
@@ -49,6 +65,14 @@ module Apiwork
           @dump[:format]
         end
 
+        # @api public
+        # Whether this param is concrete.
+        #
+        # @return [Boolean]
+        def concrete?
+          true
+        end
+
         # @api public
         # Whether this param is scalar.
         #
@@ -119,7 +143,9 @@ module Apiwork
         # @return [Hash]
         def to_h
           result = super
+          result[:default] = default
           result[:enum] = enum if enum?
+          result[:example] = example
           result[:format] = format
           result[:max] = max
           result[:min] = min

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

@@ -24,6 +24,22 @@ module Apiwork
       #     param.enum_reference? # => false
       #   end
       class Number < Base
+        # @api public
+        # The default for this param.
+        #
+        # @return [Object, nil]
+        def default
+          @dump[:default]
+        end
+
+        # @api public
+        # The example for this param.
+        #
+        # @return [Object, nil]
+        def example
+          @dump[:example]
+        end
+
         # @api public
         # The minimum for this param.
         #
@@ -40,6 +56,14 @@ module Apiwork
           @dump[:max]
         end
 
+        # @api public
+        # Whether this param is concrete.
+        #
+        # @return [Boolean]
+        def concrete?
+          true
+        end
+
         # @api public
         # Whether this param is scalar.
         #
@@ -110,7 +134,9 @@ module Apiwork
         # @return [Hash]
         def to_h
           result = super
+          result[:default] = default
           result[:enum] = enum if enum?
+          result[:example] = example
           result[:max] = max
           result[:min] = min
           result

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Apiwork
+  module Introspection
+    module Param
+      # @api public
+      # Record param representing key-value maps with typed values.
+      #
+      # @example Basic usage
+      #   param.type # => :record
+      #   param.record? # => true
+      #   param.scalar? # => false
+      #
+      # @example Value type
+      #   param.of # => Param (value type) or nil
+      class Record < Base
+        # @api public
+        # The default for this param.
+        #
+        # @return [Object, nil]
+        def default
+          @dump[:default]
+        end
+
+        # @api public
+        # The example for this param.
+        #
+        # @return [Object, nil]
+        def example
+          @dump[:example]
+        end
+
+        # @api public
+        # The value type for this record.
+        #
+        # @return [Param::Base, nil]
+        def of
+          @of ||= @dump[:of] ? Param.build(@dump[:of]) : nil
+        end
+
+        # @api public
+        # Whether this param is a record.
+        #
+        # @return [Boolean]
+        def record?
+          true
+        end
+
+        # @api public
+        # Whether this param is concrete.
+        #
+        # @return [Boolean]
+        def concrete?
+          true
+        end
+
+        # @api public
+        # Converts this param to a hash.
+        #
+        # @return [Hash]
+        def to_h
+          result = super
+          result[:default] = default
+          result[:example] = example
+          result[:of] = of&.to_h
+          result
+        end
+      end
+    end
+  end
+end

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

@@ -24,6 +24,22 @@ module Apiwork
       #     param.enum_reference? # => false
       #   end
       class String < Base
+        # @api public
+        # The default for this param.
+        #
+        # @return [Object, nil]
+        def default
+          @dump[:default]
+        end
+
+        # @api public
+        # The example for this param.
+        #
+        # @return [Object, nil]
+        def example
+          @dump[:example]
+        end
+
         # @api public
         # The format for this param.
         #
@@ -48,6 +64,14 @@ module Apiwork
           @dump[:max]
         end
 
+        # @api public
+        # Whether this param is concrete.
+        #
+        # @return [Boolean]
+        def concrete?
+          true
+        end
+
         # @api public
         # Whether this param is scalar.
         #
@@ -110,7 +134,9 @@ module Apiwork
         # @return [Hash]
         def to_h
           result = super
+          result[:default] = default
           result[:enum] = enum if enum?
+          result[:example] = example
           result[:format] = format
           result[:max] = max
           result[:min] = min

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

@@ -20,6 +20,30 @@ module Apiwork
       #     param.enum_reference? # => false
       #   end
       class Time < Base
+        # @api public
+        # The default for this param.
+        #
+        # @return [Object, nil]
+        def default
+          @dump[:default]
+        end
+
+        # @api public
+        # The example for this param.
+        #
+        # @return [Object, nil]
+        def example
+          @dump[:example]
+        end
+
+        # @api public
+        # Whether this param is concrete.
+        #
+        # @return [Boolean]
+        def concrete?
+          true
+        end
+
         # @api public
         # Whether this param is scalar.
         #
@@ -67,6 +91,18 @@ module Apiwork
         def formattable?
           false
         end
+
+        # @api public
+        # Converts this param to a hash.
+        #
+        # @return [Hash]
+        def to_h
+          result = super
+          result[:default] = default
+          result[:enum] = enum if enum?
+          result[:example] = example
+          result
+        end
       end
     end
   end

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

@@ -20,6 +20,30 @@ module Apiwork
       #     param.enum_reference? # => false
       #   end
       class UUID < Base
+        # @api public
+        # The default for this param.
+        #
+        # @return [Object, nil]
+        def default
+          @dump[:default]
+        end
+
+        # @api public
+        # The example for this param.
+        #
+        # @return [Object, nil]
+        def example
+          @dump[:example]
+        end
+
+        # @api public
+        # Whether this param is concrete.
+        #
+        # @return [Boolean]
+        def concrete?
+          true
+        end
+
         # @api public
         # Whether this param is scalar.
         #
@@ -67,6 +91,18 @@ module Apiwork
         def formattable?
           false
         end
+
+        # @api public
+        # Converts this param to a hash.
+        #
+        # @return [Hash]
+        def to_h
+          result = super
+          result[:default] = default
+          result[:enum] = enum if enum?
+          result[:example] = example
+          result
+        end
       end
     end
   end

data/lib/apiwork/introspection/param.rb

@@ -18,6 +18,7 @@ module Apiwork
           when :binary then Binary.new(dump)
           when :unknown then Unknown.new(dump)
           when :array then Array.new(dump)
+          when :record then Record.new(dump)
           when :object then Object.new(dump)
           when :union then Union.new(dump)
           when :literal then Literal.new(dump)

data/lib/apiwork/object.rb

@@ -1129,6 +1129,103 @@ module Apiwork
       )
     end
 
+    # @api public
+    # Defines an unknown.
+    #
+    # @param name [Symbol]
+    #   The 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 example [Object, nil] (nil)
+    #   The example value. 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.
+    # @return [void]
+    #
+    # @example Opaque metadata
+    #   unknown :metadata
+    def unknown(
+      name,
+      as: nil,
+      default: nil,
+      deprecated: false,
+      description: nil,
+      example: nil,
+      nullable: false,
+      optional: false,
+      required: false
+    )
+      param(
+        name,
+        as:,
+        default:,
+        deprecated:,
+        description:,
+        example:,
+        nullable:,
+        optional:,
+        required:,
+        type: :unknown,
+      )
+    end
+
+    # @api public
+    # Defines an optional unknown.
+    #
+    # @param name [Symbol]
+    #   The 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 example [Object, nil] (nil)
+    #   The example value. Metadata included in exports.
+    # @param nullable [Boolean] (false)
+    #   Whether the value can be `null`.
+    # @param required [Boolean] (false)
+    #   Whether the param is required.
+    # @return [void]
+    #
+    # @example Optional metadata
+    #   unknown? :metadata
+    def unknown?(
+      name,
+      as: nil,
+      default: nil,
+      deprecated: false,
+      description: nil,
+      example: nil,
+      nullable: false,
+      required: false
+    )
+      param(
+        name,
+        as:,
+        default:,
+        deprecated:,
+        description:,
+        example:,
+        nullable:,
+        required:,
+        optional: true,
+        type: :unknown,
+      )
+    end
+
     # @api public
     # Defines an object.
     #
@@ -1244,6 +1341,10 @@ module Apiwork
     #   Whether deprecated. Metadata included in exports.
     # @param description [String, nil] (nil)
     #   The description. Metadata included in exports.
+    # @param max [Integer, nil] (nil)
+    #   The maximum number of elements.
+    # @param min [Integer, nil] (nil)
+    #   The minimum number of elements.
     # @param nullable [Boolean] (false)
     #   Whether the value can be `null`.
     # @param of [Symbol, Hash, nil] (nil)
@@ -1267,12 +1368,30 @@ module Apiwork
     #       decimal :price
     #     end
     #   end
+    #
+    # @example Array of discriminated union
+    #   array :notifications do
+    #     union discriminator: :type do
+    #       variant tag: 'email' do
+    #         object do
+    #           string :address
+    #         end
+    #       end
+    #       variant tag: 'sms' do
+    #         object do
+    #           string :phone
+    #         end
+    #       end
+    #     end
+    #   end
     def array(
       name,
       as: nil,
       default: nil,
       deprecated: false,
       description: nil,
+      max: nil,
+      min: nil,
       nullable: false,
       of: nil,
       optional: false,
@@ -1285,6 +1404,8 @@ module Apiwork
         default:,
         deprecated:,
         description:,
+        max:,
+        min:,
         nullable:,
         of:,
         optional:,
@@ -1320,6 +1441,22 @@ module Apiwork
     #   array? :labels do
     #     string
     #   end
+    #
+    # @example Optional array of discriminated union
+    #   array? :items do
+    #     union discriminator: :type do
+    #       variant tag: 'text' do
+    #         object do
+    #           string :content
+    #         end
+    #       end
+    #       variant tag: 'image' do
+    #         object do
+    #           string :url
+    #         end
+    #       end
+    #     end
+    #   end
     def array?(
       name,
       as: nil,
@@ -1346,6 +1483,113 @@ module Apiwork
       )
     end
 
+    # @api public
+    # Defines a record.
+    #
+    # @param name [Symbol]
+    #   The 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 defining value type
+    # @return [void]
+    #
+    # @example Record of integers
+    #   record :scores do
+    #     integer
+    #   end
+    #
+    # @example Record of objects
+    #   record :settings do
+    #     object do
+    #       string :value
+    #       boolean :enabled
+    #     end
+    #   end
+    def record(
+      name,
+      as: nil,
+      default: nil,
+      deprecated: false,
+      description: nil,
+      nullable: false,
+      optional: false,
+      required: false,
+      &block
+    )
+      param(
+        name,
+        as:,
+        default:,
+        deprecated:,
+        description:,
+        nullable:,
+        optional:,
+        required:,
+        type: :record,
+        &block
+      )
+    end
+
+    # @api public
+    # Defines an optional record.
+    #
+    # @param name [Symbol]
+    #   The 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 required [Boolean] (false)
+    #   Whether the param is required.
+    # @yield block defining value type
+    # @return [void]
+    #
+    # @example Optional record
+    #   record? :metadata do
+    #     string
+    #   end
+    def record?(
+      name,
+      as: nil,
+      default: nil,
+      deprecated: false,
+      description: nil,
+      nullable: false,
+      required: false,
+      &block
+    )
+      param(
+        name,
+        as:,
+        default:,
+        deprecated:,
+        description:,
+        nullable:,
+        required:,
+        optional: true,
+        type: :record,
+        &block
+      )
+    end
+
     # @api public
     # Defines a union.
     #
@@ -1552,6 +1796,8 @@ module Apiwork
       optional: false,
       required: false
     )
+      reference_type = to || name
+
       param(
         name,
         as:,
@@ -1561,7 +1807,8 @@ module Apiwork
         nullable:,
         optional:,
         required:,
-        type: to || name,
+        custom_type: reference_type,
+        type: reference_type,
       )
     end
 
@@ -1598,6 +1845,8 @@ module Apiwork
       nullable: false,
       required: false
     )
+      reference_type = to || name
+
       param(
         name,
         as:,
@@ -1606,8 +1855,9 @@ module Apiwork
         description:,
         nullable:,
         required:,
+        custom_type: reference_type,
         optional: true,
-        type: to || name,
+        type: reference_type,
       )
     end
 

data/lib/apiwork/representation/attribute.rb

@@ -117,7 +117,7 @@ module Apiwork
           element.validate!
           @element = element
           type = element.type
-          @of = element.inner&.type if element.type == :array
+          @of = element.inner&.type if [:array, :record].include?(element.type)
         end
 
         if owner_representation_class.model_class.present?