jsapi 2.0 → 2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbb6b0f27ef5b970e527367f2e918502d935765e4201ddbf5376fa4566ed5fde
-  data.tar.gz: d4764ceb8c1e32d0368a14d2d09370696f0329eb69f745ccdb9da67e5dcd0b1b
+  metadata.gz: 9d75f4e95d037fa1516504cff963dca3409cc1b45233fe6a46bab2155939e249
+  data.tar.gz: 3e6626ac1b7796eb94cbbdabe57df7f9b286947018133ef4cdac93f241e8214a
 SHA512:
-  metadata.gz: d996c4830b339e80c9de07bf379d239734de9f0df4d9f1cd0072ae358c755a07aeee5a54bbbbe6cb2dae4452e3fba0c8691d6a641a74ac8ef7014b00b64d51dd
-  data.tar.gz: ea2bf03ff17664bcb434f160e13e17e5d2eb341fb7c17ceddf6667d4fbcd6db297eee0c93c66a8d530a2da1032bf33b983385c05e88bd9a431a68b0062a4b08e
+  metadata.gz: 4fdf2b1bc207755bb94dc88f001d4d668e7b7506284358b8f08531f15869d1feb1b7eebcd5cced2277e2cba42ebdae907f254668f13f7d9295db4c42298a531a
+  data.tar.gz: 3d6a20ef5a0218e2ac75233792dc844389853bfb24167d3f9ec0f4919f00a1e7623aa7a5801c10649cb02d8c30c0eb9e781901da2d488ebc4134b3492e1bdef5

data/lib/jsapi/controller/methods.rb

@@ -127,6 +127,12 @@ module Jsapi
       [true, false].each do |bang|
         define_method(bang ? :api_operation! : :api_operation) \
         do |operation_name = nil, omit: nil, status: nil, strong: false, &block|
+          raise ArgumentError, Messages.invalid_value(
+            name: 'omit',
+            value: omit,
+            valid_values: %i[empty nil]
+          ) if [nil, :empty, :nil].exclude?(omit)
+
           operation = _api_operation(operation_name)
           response_model = nil
 
@@ -247,6 +253,12 @@ module Jsapi
       # - +:empty+ - All of the  properties whose value is empty are omitted.
       # - +:nil+ - All of the properties whose value is +nil+ are omitted.
       def api_response(result, operation_name = nil, omit: nil, status: nil)
+        raise ArgumentError, Messages.invalid_value(
+          name: 'omit',
+          value: omit,
+          valid_values: %i[empty nil]
+        ) if [nil, :empty, :nil].exclude?(omit)
+
         status = Status::Code.from(status)
         operation = _api_operation(operation_name)
         response_model = _api_response_model(operation, status)

data/lib/jsapi/controller/response.rb

@@ -4,44 +4,6 @@ module Jsapi
   module Controller
     # Used to jsonify a response.
     class Response
-      class JsonifyError < RuntimeError # :nodoc:
-        def message
-          [@path&.delete_prefix('.') || 'response body', super].join(' ')
-        end
-
-        def prepend(origin)
-          @path = "#{origin}#{@path}"
-          self
-        end
-      end
-
-      class HashReader # :nodoc:
-        delegate_missing_to :@hash
-
-        def initialize(hash)
-          @hash = hash
-        end
-
-        def [](key)
-          return unless @hash.key?(key)
-
-          (@read_keys ||= []) << key
-          @hash[key]
-        end
-
-        def additional_properties
-          if @hash.key?('additional_properties')
-            @hash['additional_properties']
-          elsif @hash.key?(:additional_properties)
-            @hash[:additional_properties]
-          elsif @read_keys
-            @hash.except(*@read_keys)
-          else
-            @hash
-          end
-        end
-      end
-
       # Creates a new instance to jsonify +object+ according to +content_model+.
       #
       # The +:omit+ option specifies on which conditions properties are omitted.
@@ -49,29 +11,25 @@ module Jsapi
       #
       # - +:empty+ - All of the  properties whose value is empty are omitted.
       # - +:nil+ - All of the properties whose value is +nil+ are omitted.
-      #
-      # Raises an +ArgumentError+ when +:omit+ is other than +:empty+, +:nil+ or +nil+.
-      def initialize(object, content_model, omit: nil, locale: nil)
+      def initialize(object, content_model, locale: nil, omit: nil)
         @object = object
         @content_model = content_model
-
-        @omittable_check =
-          case omit
-          when nil
-            nil
-          when :nil
-            ->(value, schema) { schema.omittable? && value.nil? }
-          when :empty
-            ->(value, schema) { schema.omittable? && value.try(:empty?) }
-          else
-            raise ArgumentError, Messages.invalid_value(
-              name: 'omit',
-              value: omit,
-              valid_values: %i[empty nil]
-            )
-          end
-
         @locale = locale
+        @omit = omit
+      end
+
+      # Returns the \JSON representation of the response.
+      def as_json(*)
+        with_locale do
+          @content_model.schema.jsonify(
+            @object,
+            context: :response,
+            omit: @omit
+          )
+        end
+      rescue JsonifyError => e
+        e.prepend('response body') if e.path.blank?
+        raise e
       end
 
       def inspect # :nodoc:
@@ -80,24 +38,35 @@ module Jsapi
 
       # Returns the \JSON representation of the response as a string.
       def to_json(*)
-        with_locale { jsonify(@object, @content_model.schema) }.to_json
+        as_json.to_json
       end
 
       # Writes the response in \JSON sequence text format to +stream+.
       def write_json_seq_to(stream)
         schema = @content_model.schema
+        object = @object
+        object = schema.default_value(context: :response) if object.nil?
+
         with_locale do
           items, item_schema =
-            if schema.array? && @object.respond_to?(:each)
-              [@object, schema.items]
+            if schema.array? && object.respond_to?(:each)
+              [object, schema.items]
             else
-              [[@object], schema]
+              [[object], schema]
             end
 
-          items.each do |item|
+          items.each_with_index do |item, index|
             stream.write("\u001E") # Record separator (see RFC 7464)
-            stream.write(jsonify(item, item_schema).to_json)
+            stream.write(
+              item_schema.jsonify(
+                item,
+                context: :response,
+                omit: @omit
+              ).to_json
+            )
             stream.write("\n")
+          rescue JsonifyError => e
+            raise e.prepend("[#{index}]")
           end
         end
         nil
@@ -105,88 +74,6 @@ module Jsapi
 
       private
 
-      def jsonify(object, schema)
-        object = schema.default_value(context: :response) if object.nil?
-
-        if object.nil?
-          raise JsonifyError, "can't be nil" unless schema.nullable?
-        else
-          case schema.type
-          when 'array'
-            jsonify_array(object, schema)
-          when 'boolean'
-            object
-          when 'integer'
-            schema.convert(object.to_i)
-          when 'number'
-            schema.convert(object.to_f)
-          when 'object'
-            jsonify_object(object, schema)
-          when 'string'
-            schema.convert(
-              case schema.format
-              when 'date'
-                object.to_date
-              when 'date-time'
-                object.to_datetime
-              when 'duration'
-                object.iso8601
-              else
-                object.to_s
-              end
-            )
-          else
-            raise JsonifyError, "has an invalid type: #{schema.type.inspect}"
-          end
-        end
-      end
-
-      def jsonify_array(array, schema)
-        item_schema = schema.items
-        index = 0
-
-        Array(array).map do |item|
-          item = jsonify(item, item_schema)
-          index += 1
-          item
-        rescue JsonifyError => e
-          raise e.prepend("[#{index}]")
-        end
-      end
-
-      def jsonify_object(object, schema)
-        schema = schema.resolve_schema(object, context: :response)
-        additional_properties = schema.additional_properties
-        object = HashReader.new(object) if additional_properties && object.is_a?(Hash)
-
-        {}.tap do |properties|
-          # Add properties
-          schema.resolve_properties(context: :response).each_value do |property|
-            property_schema = property.schema
-            property_value = property.reader.call(object)
-            property_value = property_schema.default if property_value.nil?
-            next if @omittable_check&.call(property_value, property_schema)
-
-            properties[property.name] = jsonify(property_value, property_schema)
-          rescue JsonifyError => e
-            raise e.prepend(".#{property.name}")
-          end
-          # Add additional properties
-          if additional_properties
-            additional_properties_schema = additional_properties.schema
-
-            additional_properties.source.call(object)&.each do |key, value|
-              key = key.to_s
-              next if properties.key?(key)
-
-              properties[key] = jsonify(value, additional_properties_schema)
-            rescue JsonifyError => e
-              raise e.prepend(".#{key}")
-            end
-          end
-        end.presence
-      end
-
       def with_locale(&block)
         if @locale
           I18n.with_locale(@locale, &block)

data/lib/jsapi/jsonify_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Jsapi
+  # Raised when jsonifying an object fails.
+  class JsonifyError < RuntimeError
+    attr_reader :path # :nodoc:
+
+    def message
+      [@path&.delete_prefix('.'), super].compact.join(' ')
+    end
+
+    def prepend(origin) # :nodoc:
+      @path = "#{origin}#{@path}"
+      self
+    end
+  end
+end

data/lib/jsapi/meta/content.rb

@@ -36,10 +36,19 @@ module Jsapi
         @schema = Schema.new(keywords)
       end
 
+      # Returns the data value of the first example.
+      def example_data_value(definitions, locale: nil)
+        examples
+          .values.first
+          &.resolve(definitions)
+          &.data_value(builder: example_builder(definitions, locale))
+      end
+
       # Returns a hash representing the \OpenAPI media type object describing
       # the content. Applies to \OpenAPI 3.0 and higher.
-      def to_openapi(version, media_type = nil)
+      def to_openapi(version, definitions = nil, locale: nil, media_type: nil)
         version = OpenAPI::Version.from(version)
+        example_builder = nil
 
         with_openapi_extensions(
           **if media_type == Media::Type::APPLICATION_JSON_SEQ &&
@@ -50,10 +59,17 @@ module Jsapi
             end,
           examples:
             examples.transform_values do |example|
-              example.to_openapi(version)
+              example_builder ||= example_builder(definitions, locale)
+              example.to_openapi(version, builder: example_builder)
             end.presence
         )
       end
+
+      private
+
+      def example_builder(definitions, locale)
+        Example::Builder.new(schema, definitions, locale: locale) if definitions.present?
+      end
     end
   end
 end

data/lib/jsapi/meta/definitions.rb

@@ -313,6 +313,10 @@ module Jsapi
         end
       end
 
+      ##
+      # :method: find_example
+      # Returns the reusable example with the specified name.
+
       ##
       # :method: find_parameter
       # Returns the reusable parameter with the specified name.
@@ -333,7 +337,8 @@ module Jsapi
       # :method: find_security_scheme
       # Returns the security scheme with the specified name.
 
-      %i[parameters request_bodies responses schemas security_schemes].each do |attribute_name|
+      %i[examples parameters request_bodies responses
+         schemas security_schemes].each do |attribute_name|
         define_method(:"find_#{attribute_name.to_s.singularize}") do |name|
           cached_attributes.dig(attribute_name, name&.to_s)
         end

data/lib/jsapi/meta/example/base.rb

@@ -29,7 +29,7 @@ module Jsapi
 
         ##
         # :attr: value
-        # The sample value.
+        # The sample value. Can be a +Proc+.
         attribute :value
 
         def external_value=(value) # :nodoc:
@@ -41,7 +41,7 @@ module Jsapi
           end
         end
 
-        def serialized_value=(value)  # :nodoc:
+        def serialized_value=(value) # :nodoc:
           try_modify_attribute!(:serialized_value) do
             raise 'external value and serialized value are mutually exclusive' \
             unless external_value.nil?
@@ -50,18 +50,27 @@ module Jsapi
           end
         end
 
+        # Returns the data structure of the sample value.
+        def data_value(builder: nil)
+          value = self.value
+          return value unless value.is_a?(Proc)
+
+          value.arity.zero? ? value.call : value.call(builder)
+        end
+
         # Returns a hash representing the \OpenAPI example object.
-        def to_openapi(version, *)
+        def to_openapi(version, *, builder: nil)
           version = OpenAPI::Version.from(version)
+          data_value = data_value(builder: builder)
 
           with_openapi_extensions(
             summary: summary,
             description: description,
             **if version < OpenAPI::V3_2
-                { value: value }
+                { value: data_value }
               else
                 {
-                  dataValue: value,
+                  dataValue: data_value,
                   serializedValue: serialized_value
                 }
               end,

data/lib/jsapi/meta/example/builder.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Example
+      class Builder # :nodoc:
+        def initialize(schema, definitions, locale: nil)
+          @schema = Schema.wrap(schema, definitions)
+          @locale = locale
+        end
+
+        def generate_json(object, omit: nil)
+          raise ArgumentError, Messages.invalid_value(
+            name: 'omit',
+            value: omit,
+            valid_values: %i[empty nil]
+          ) if [nil, :empty, :nil].exclude?(omit)
+
+          with_locale { @schema.jsonify(object, omit: omit) }
+        end
+
+        private
+
+        def with_locale(&block)
+          if @locale
+            I18n.with_locale(@locale, &block)
+          else
+            yield
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/example.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'example/base'
+require_relative 'example/builder'
 require_relative 'example/reference'
 
 module Jsapi

data/lib/jsapi/meta/operation.rb

@@ -278,7 +278,7 @@ module Jsapi
                   parameters.values.flat_map do |parameter|
                     parameter.to_openapi_parameters(version, definitions)
                   end,
-                request_body: request_body&.to_openapi(version)
+                requestBody: request_body&.to_openapi(version)
               }
             end,
           responses:

data/lib/jsapi/meta/response/base.rb

@@ -104,7 +104,7 @@ module Jsapi
           with_openapi_extensions(
             if version == OpenAPI::V2_0
               media_type, content = contents.first
-              example = content&.examples&.values&.first
+              example = content&.example_data_value(definitions, locale: locale)
               {
                 description: description,
                 schema: content&.schema&.to_openapi(version),
@@ -114,7 +114,7 @@ module Jsapi
                   end.compact.presence,
                 examples:
                   if media_type.present? && example.present?
-                    { media_type => example.resolve(definitions).value }
+                    { media_type => example }
                   end
               }
             else
@@ -127,7 +127,15 @@ module Jsapi
                   end.presence,
                 content:
                   contents.to_h do |nth_media_type, nth_content|
-                    [nth_media_type, nth_content.to_openapi(version, nth_media_type)]
+                    [
+                      nth_media_type,
+                      nth_content.to_openapi(
+                        version,
+                        definitions,
+                        locale: locale,
+                        media_type: nth_media_type
+                      )
+                    ]
                   end.presence,
                 links:
                   links.transform_values do |link|

data/lib/jsapi/meta/response/wrapper.rb

@@ -12,6 +12,10 @@ module Jsapi
           super
         end
 
+        def contents
+          super.transform_values { |content| Content.wrap(content, definitions) }
+        end
+
         def media_type_and_content_for(*media_ranges)
           super&.then do |media_type_and_content|
             [

data/lib/jsapi/meta/schema/array.rb

@@ -8,6 +8,16 @@ module Jsapi
           def items
             @items ||= Schema.wrap(super, definitions)
           end
+
+          private
+
+          def jsonify_value(value, context:, omit:)
+            Array(value).each_with_index.map do |item, index|
+              items.jsonify(item, context: context, omit: omit)
+            rescue JsonifyError => e
+              raise e.prepend("[#{index}]")
+            end
+          end
         end
 
         ##

data/lib/jsapi/meta/schema/boolean.rb

@@ -3,7 +3,15 @@
 module Jsapi
   module Meta
     module Schema
-      class Boolean < Base; end
+      class Boolean < Base
+        class Wrapper < Schema::Wrapper
+          private
+
+          def jsonify_value(value, **)
+            value ? true : false
+          end
+        end
+      end
     end
   end
 end

data/lib/jsapi/meta/schema/conversion.rb

@@ -10,13 +10,13 @@ module Jsapi
           base.attr_accessor :conversion
         end
 
-        def convert(object)
-          return object if conversion.nil?
+        def convert(value)
+          return value if conversion.nil?
 
           if conversion.respond_to?(:call)
-            conversion.call(object)
+            conversion.call(value)
           else
-            object.send(conversion)
+            value.send(conversion)
           end
         end
       end

data/lib/jsapi/meta/schema/integer.rb

@@ -3,7 +3,15 @@
 module Jsapi
   module Meta
     module Schema
-      class Integer < Numeric; end
+      class Integer < Numeric
+        class Wrapper < Schema::Wrapper
+          private
+
+          def jsonify_value(value, **)
+            convert(value.to_i)
+          end
+        end
+      end
     end
   end
 end

data/lib/jsapi/meta/schema/number.rb

@@ -3,7 +3,15 @@
 module Jsapi
   module Meta
     module Schema
-      class Number < Numeric; end
+      class Number < Numeric
+        class Wrapper < Schema::Wrapper
+          private
+
+          def jsonify_value(value, **)
+            convert(value.to_f)
+          end
+        end
+      end
     end
   end
 end

data/lib/jsapi/meta/schema/object.rb

@@ -5,6 +5,33 @@ module Jsapi
     module Schema
       class Object < Base
         class Wrapper < Schema::Wrapper
+          class HashReader # :nodoc:
+            delegate_missing_to :@hash
+
+            def initialize(hash)
+              @hash = hash
+            end
+
+            def [](key)
+              return unless @hash.key?(key)
+
+              (@read_keys ||= []) << key
+              @hash[key]
+            end
+
+            def additional_properties
+              if @hash.key?('additional_properties')
+                @hash['additional_properties']
+              elsif @hash.key?(:additional_properties)
+                @hash[:additional_properties]
+              elsif @read_keys
+                @hash.except(*@read_keys)
+              else
+                @hash
+              end
+            end
+          end
+
           def additional_properties
             AdditionalProperties.wrap(super, definitions)
           end
@@ -58,6 +85,52 @@ module Jsapi
               .new(schema.resolve(definitions), definitions)
               .resolve_schema(object, context: context)
           end
+
+          private
+
+          def jsonify_value(value, context:, omit:)
+            schema = resolve_schema(value, context: context)
+            additional_properties = schema.additional_properties
+            value = HashReader.new(value) if additional_properties && value.is_a?(Hash)
+
+            {}.tap do |properties|
+              # Add properties
+              schema.resolve_properties(context: context).each_value do |property|
+                property_schema = property.schema
+                property_value = property.reader.call(value)
+                property_value = property_schema.default if property_value.nil?
+
+                if property_schema.omittable?
+                  next if omit == :nil && property_value.nil?
+                  next if omit == :empty && (property_value.nil? || property_value.try(:empty?))
+                end
+
+                properties[property.name] = property_schema.jsonify(
+                  property_value,
+                  context: context
+                )
+              rescue JsonifyError => e
+                raise e.prepend(".#{property.name}")
+              end
+              # Add additional properties
+              if additional_properties
+                additional_properties_schema = additional_properties.schema
+
+                additional_properties.source.call(value)&.each \
+                do |property_name, property_value|
+                  property_name = property_name.to_s
+                  next if properties.key?(property_name)
+
+                  properties[property_name] = additional_properties_schema.jsonify(
+                    property_value,
+                    context: context
+                  )
+                rescue JsonifyError => e
+                  raise e.prepend(".#{property_name}")
+                end
+              end
+            end.presence
+          end
         end
 
         ##

data/lib/jsapi/meta/schema/string.rb

@@ -6,6 +6,28 @@ module Jsapi
       class String < Base
         include Conversion
 
+        class Wrapper < Schema::Wrapper # :nodoc:
+          private
+
+          def jsonify_value(value, **)
+            convert(
+              case format
+              when 'date'
+                value.to_date.as_json
+              when 'date-time'
+                value.to_datetime.as_json
+              when 'duration'
+                value = ActiveSupport::Duration.parse(value) \
+                unless value.is_a?(ActiveSupport::Duration)
+
+                value.iso8601
+              else
+                value.to_s
+              end
+            )
+          end
+        end
+
         ##
         # :attr: format
         # The format of a string.

data/lib/jsapi/meta/schema/wrapper.rb

@@ -25,6 +25,20 @@ module Jsapi
 
           definitions.default_value(type, context: context)
         end
+
+        # Generates a JSON value representing +value+.
+        def jsonify(value, context: nil, omit: nil)
+          value = default_value(context: context) if value.nil?
+          raise JsonifyError, "can't be nil" if value.nil? && !nullable?
+
+          jsonify_value(value, context: context, omit: omit) unless value.nil?
+        end
+
+        private
+
+        def jsonify_value(value, **)
+          value
+        end
       end
     end
   end

data/lib/jsapi/meta/schema.rb

@@ -65,14 +65,9 @@ module Jsapi
           return if schema.nil?
           return schema if schema.is_a?(Wrapper)
 
-          case schema.resolve(definitions).type
-          when 'array'
-            Array::Wrapper
-          when 'object'
-            Object::Wrapper
-          else
-            Wrapper
-          end.new(schema, definitions)
+          "#{schema.resolve(definitions).class.name}::Wrapper"
+            .constantize
+            .new(schema, definitions)
         end
       end
     end

data/lib/jsapi/version.rb

@@ -5,6 +5,6 @@ module Jsapi
     # NOTE: See https://bundler.io/guides/creating_gem.html
 
     # The current GEM version.
-    VERSION = '2.0'
+    VERSION = '2.1'
   end
 end

data/lib/jsapi.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'jsapi/messages'
+require 'jsapi/jsonify_error'
 require 'jsapi/configuration'
 require 'jsapi/media'
 require 'jsapi/status'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsapi
 version: !ruby/object:Gem::Version
-  version: '2.0'
+  version: '2.1'
 platform: ruby
 authors:
 - Denis Göller
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-18 00:00:00.000000000 Z
+date: 2026-09-02 00:00:00.000000000 Z
 dependencies: []
 description:
 email: denis@dmgoeller.de
@@ -58,6 +58,7 @@ files:
 - lib/jsapi/json/object.rb
 - lib/jsapi/json/string.rb
 - lib/jsapi/json/value.rb
+- lib/jsapi/jsonify_error.rb
 - lib/jsapi/media.rb
 - lib/jsapi/media/range.rb
 - lib/jsapi/media/type.rb
@@ -76,6 +77,7 @@ files:
 - lib/jsapi/meta/definitions.rb
 - lib/jsapi/meta/example.rb
 - lib/jsapi/meta/example/base.rb
+- lib/jsapi/meta/example/builder.rb
 - lib/jsapi/meta/example/reference.rb
 - lib/jsapi/meta/existence.rb
 - lib/jsapi/meta/external_documentation.rb