jsapi 1.4 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87f305e41facfb84c96e5e2406b636aa9e10a27545a25d42a5029f4d4dd93488
-  data.tar.gz: 6723179cd4981c590a4e8f0c45808d9b69a0436be48e1e89f06c7ef0a4b56ddb
+  metadata.gz: 7651bda7e379186840e78ede1870f022b69deca559b6ba5ad6d0cbc8aac5c840
+  data.tar.gz: 16a661d4c24e1195f23d6fa0a23d27ba53fb944819b2f9a57c2174456f5ca913
 SHA512:
-  metadata.gz: 7ddefbaaa678ed70e29055dbe4452ee0f4f738fa2386e8e3f5dbaa42e682ca973fa0bd04e5c6b22b2570bfd290fd4fcfbb42c8f7e50650ffda50d0cfbb160cc7
-  data.tar.gz: 3fc210ea9c236f319f1c94dcb741d7d910eb7edb90020aafcbbee2a033bd232a9bb88dd26fc306869f7c3be715487f4655a517e5968f63461a6bbad57074099a
+  metadata.gz: 0e1eebb7f9d53a3e2f28a562edac148093b506ade987384e093530f5d337b85a5aabeb5acae70ca80233f75215e1dbc158b4a786724a8eb77670e63ee0be348d
+  data.tar.gz: 51d183148b0575ba9d437c2d3208257ab6e0b1cdec9d3024aa63a6261a56542e9bee8907acc4bb5f042360f90114bf668f1e46836e97dcf1332d30b616f8d264

data/lib/jsapi/controller/methods.rb

@@ -12,12 +12,16 @@ module Jsapi
         self.class.api_definitions
       end
 
+      ##
+      # :method: api_operation
+      # :args: operation_name = nil, omit: nil, status: nil, strong: false, &block
+      #
       # Performs an API operation by calling the given block. The request parameters are
       # passed as an instance of the operation's model class to the block. The object
       # returned by the block is implicitly rendered according to the appropriate +response+
-      # specification when the content type is a JSON MIME type. When content type is
+      # specification when the content type is a \JSON MIME type. When content type is
       # <code>application/json-seq</code>, the object returned by the block is streamed in
-      # JSON sequence text format.
+      # \JSON sequence text format.
       #
       #   api_operation('foo') do |api_params|
       #     # ...
@@ -36,41 +40,68 @@ module Jsapi
       # - +:nil+ - All of the properties whose value is +nil+ are omitted.
       #
       # Raises an +ArgumentError+ when +:omit+ is other than +:empty+, +:nil+ or +nil+.
-      def api_operation(operation_name = nil,
-                        omit: nil,
-                        status: nil,
-                        strong: false,
-                        &block)
-        _api_operation(
-          operation_name,
-          bang: false,
-          omit: omit,
-          status: status,
-          strong: strong,
-          &block
-        )
-      end
 
-      # Like +api_operation+, except that a ParametersInvalid exception is raised on
-      # invalid request parameters.
+      ##
+      # :method: api_operation!
+      # :args: operation_name = nil, omit: nil, status: nil, strong: false, &block
+      #
+      # Like +api_operation+, except that a ParametersInvalid exception is raised
+      # when request parameters are invalid.
       #
       #   api_operation!('foo') do |api_params|
       #     # ...
       #   end
-      #
-      def api_operation!(operation_name = nil,
-                         omit: nil,
-                         status: nil,
-                         strong: false,
-                         &block)
-        _api_operation(
-          operation_name,
-          bang: true,
-          omit: omit,
-          status: status,
-          strong: strong,
-          &block
-        )
+
+      [true, false].each do |bang|
+        define_method(bang ? :api_operation! : :api_operation) \
+        do |operation_name = nil, omit: nil, status: nil, strong: false, &block|
+          definitions = api_definitions
+          operation_model = _find_api_operation_model(operation_name, definitions)
+          response_model = _find_api_response_model(operation_model, status, definitions)
+          head(status) && return unless block
+
+          # Perform operation
+          api_params = _api_params(operation_model, definitions, strong: strong)
+          api_response = Response.new(
+            begin
+              raise ParametersInvalid.new(api_params) if bang && api_params.invalid?
+
+              block.call(api_params)
+            rescue StandardError => e
+              # Lookup a rescue handler
+              rescue_handler = definitions.rescue_handler_for(e)
+              raise e if rescue_handler.nil?
+
+              # Change the HTTP status code and response model
+              status = rescue_handler.status
+              response_model = operation_model.response(status)&.resolve(definitions)
+              raise e if response_model.nil?
+
+              # Call on_rescue callbacks
+              definitions.on_rescue_callbacks.each do |callback|
+                callback.respond_to?(:call) ? callback.call(e) : send(callback, e)
+              end
+
+              Error.new(e, status: status)
+            end,
+            response_model, definitions, omit: omit
+          )
+          # Write response
+          media_type = response_model.content_type
+
+          if media_type == Media::Type::APPLICATION_JSON_SEQ
+            self.content_type = media_type.to_s
+            response.status = status
+
+            response.stream.tap do |stream|
+              api_response.write_json_seq_to(stream)
+            ensure
+              stream.close
+            end
+          elsif media_type.json?
+            render(json: api_response, status: status, content_type: media_type.to_s)
+          end
+        end
       end
 
       # Returns the request parameters as an instance of the operation's model class.
@@ -88,7 +119,7 @@ module Jsapi
       def api_params(operation_name = nil, strong: false)
         definitions = api_definitions
         _api_params(
-          _find_api_operation(operation_name, definitions),
+          _find_api_operation_model(operation_name, definitions),
           definitions,
           strong: strong
         )
@@ -110,89 +141,34 @@ module Jsapi
       # Raises an +ArgumentError+ when +:omit+ is other than +:empty+, +:nil+ or +nil+.
       def api_response(result, operation_name = nil, omit: nil, status: nil)
         definitions = api_definitions
-        operation = _find_api_operation(operation_name, definitions)
-        response_model = _api_response(operation, status, definitions)
+        operation_model = _find_api_operation_model(operation_name, definitions)
+        response_model = _find_api_response_model(operation_model, status, definitions)
 
-        Response.new(result, response_model, api_definitions, omit: omit)
+        Response.new(result, response_model, definitions, omit: omit)
       end
 
       private
 
-      def _api_operation(operation_name, bang:, omit:, status:, strong:, &block)
-        definitions = api_definitions
-        operation = _find_api_operation(operation_name, definitions)
-
-        # Perform operation
-        response_model = _api_response(operation, status, definitions)
-        head(status) && return unless block
-
-        params = _api_params(operation, definitions, strong: strong)
-
-        result = begin
-          raise ParametersInvalid.new(params) if bang && params.invalid?
-
-          block.call(params)
-        rescue StandardError => e
-          # Lookup a rescue handler
-          rescue_handler = definitions.rescue_handler_for(e)
-          raise e if rescue_handler.nil?
-
-          # Change the HTTP status code and response model
-          status = rescue_handler.status
-          response_model = operation.response(status)&.resolve(definitions)
-          raise e if response_model.nil?
-
-          # Call on_rescue callbacks
-          definitions.on_rescue_callbacks.each do |callback|
-            if callback.respond_to?(:call)
-              callback.call(e)
-            else
-              send(callback, e)
-            end
-          end
-
-          Error.new(e, status: status)
-        end
-
-        # Write response
-        return unless response_model.json_type? || response_model.json_seq_type?
-
-        response = Response.new(result, response_model, definitions, omit: omit)
-        self.content_type = response_model.content_type
-
-        if response_model.json_seq_type?
-          self.response.status = status
-
-          self.response.stream.tap do |stream|
-            response.write_json_seq_to(stream)
-          ensure
-            stream.close
-          end
-        else
-          render(json: response, status: status)
-        end
-      end
-
-      def _api_params(operation, definitions, strong:)
-        (operation.model || Model::Base).new(
+      def _api_params(operation_model, definitions, strong:)
+        (operation_model.model || Model::Base).new(
           Parameters.new(
             params.except(:action, :controller, :format).permit!,
             request,
-            operation,
+            operation_model,
             definitions,
             strong: strong
           )
         )
       end
 
-      def _api_response(operation, status, definitions)
+      def _find_api_response_model(operation, status, definitions)
         response = operation.response(status)
         return response.resolve(definitions) if response
 
         raise "status code not defined: #{status}"
       end
 
-      def _find_api_operation(operation_name, definitions)
+      def _find_api_operation_model(operation_name, definitions)
         operation = definitions.find_operation(operation_name)
         return operation if operation
 

data/lib/jsapi/media/range.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative 'type_and_subtype'
+
+module Jsapi
+  module Media
+    # Represents a media range.
+    class Range
+      include Comparable
+      include TypeAndSubtype
+
+      class << self
+        # Transforms +value+ to an instance of this class.
+        #
+        # Raises an ArgumentError when +value+ could not be transformed.
+        def from(value)
+          media_range = try_from(value)
+          return media_range unless media_range.nil?
+
+          raise ArgumentError, "invalid media range: #{value.inspect}"
+        end
+
+        # Tries to transform +value+ to an instance of this class. Returns nil
+        # if +value+ could not be transformed.
+        def try_from(value)
+          return value if value.is_a?(Range)
+
+          type_and_subtype = pattern.match(value.to_s)&.captures
+          new(*type_and_subtype) if type_and_subtype&.count == 2
+        end
+
+        private
+
+        def pattern
+          @pattern ||= begin
+            name = '[0-9a-zA-Z-]+'
+            %r{(\*|#{name})/(\*|(?:#{name}(?:\.#{name})?(?:\+#{name})?))}.freeze
+          end
+        end
+      end
+
+      # Compares it with +other+ by +priority+.
+      def <=>(other)
+        return unless other.is_a?(self.class)
+
+        result = priority <=> other.priority
+        return result unless result.zero?
+
+        result = type <=> other.type
+        return result unless result.zero?
+
+        subtype <=> other.subtype
+      end
+
+      # Returns true if the given media type matches the media range.
+      def match?(media_type)
+        media_type = Type.from(media_type) unless media_type.nil?
+
+        (type == '*' || type == media_type&.type) &&
+          (subtype == '*' || subtype == media_type&.subtype)
+      end
+
+      # Returns the level of priority of the media range.
+      def priority
+        @priority ||= (type == '*' ? 2 : 0) + (subtype == '*' ? 1 : 0) + 1
+      end
+    end
+  end
+end

data/lib/jsapi/media/type.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative 'type_and_subtype'
+
+module Jsapi
+  module Media
+    # Represents a media type.
+    class Type
+      include Comparable
+      include TypeAndSubtype
+
+      # The <code>"application/json"</code> media type.
+      APPLICATION_JSON = Type.new('application', 'json')
+
+       # The <code>"application/json-seq"</code> media type.
+      APPLICATION_JSON_SEQ = Type.new('application', 'json-seq')
+
+      class << self
+        # Transforms +value+ to an instance of this class.
+        #
+        # Raises an ArgumentError when +value+ could not be transformed.
+        def from(value)
+          media_type = try_from(value)
+          return media_type unless media_type.nil?
+
+          raise ArgumentError, "invalid media type: #{value.inspect}"
+        end
+
+        # Tries to transform +value+ to an instance of this class. Returns nil
+        # if +value+ could not be transformed.
+        def try_from(value)
+          return value if value.is_a?(Type)
+
+          type_and_subtype = pattern.match(value.to_s)&.captures
+          new(*type_and_subtype) if type_and_subtype&.count == 2
+        end
+
+        private
+
+        def pattern
+          @pattern ||= begin
+            name = '[0-9a-zA-Z-]+'
+            %r{(#{name})/(#{name}(?:\.#{name})?(?:\+#{name})?)}.freeze
+          end
+        end
+      end
+
+      # Compares it with +other+ by +type+ and +subtype+.
+      def <=>(other)
+        return unless other.is_a?(self.class)
+
+        result = type <=> other.type
+        return result unless result.zero?
+
+        subtype <=> other.subtype
+      end
+
+      # Returns true if it represents a JSON media type as specified by
+      # https://mimesniff.spec.whatwg.org/#json-mime-type.
+      def json?
+        (type.in?(%w[application text]) && subtype == 'json') ||
+          subtype.end_with?('+json')
+      end
+    end
+  end
+end

data/lib/jsapi/media/type_and_subtype.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Media
+    module TypeAndSubtype # :nodoc:
+      def self.included(base)
+        base.attr_reader :type, :subtype
+      end
+
+      def initialize(type, subtype)
+        @type = type.downcase
+        @subtype = subtype.downcase
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          type == other.type &&
+          subtype == other.subtype
+      end
+
+      alias eql? ==
+
+      def hash
+        @hash ||= [type, subtype].hash
+      end
+
+      def inspect
+        "#<#{self.class} #{to_s.inspect}>"
+      end
+
+      def to_s
+        @to_s ||= "#{type}/#{subtype}"
+      end
+
+      alias as_json to_s
+    end
+  end
+end

data/lib/jsapi/media.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'media/range'
+require_relative 'media/type'

data/lib/jsapi/meta/definitions.rb

@@ -266,17 +266,18 @@ module Jsapi
           ]
         end.presence
 
-        openapi_objects =
-          if version.major == 2
-            %i[base_path external_docs info host parameters responses parameters schemas
-               schemes security_requirements security_schemes tags]
+        openapi_objects = (
+          %i[external_docs info parameters responses schemas
+             security_requirements security_schemes tags] +
+          if version == OpenAPI::V2_0
+            %i[base_path host schemes]
           else
-            %i[callbacks examples external_docs headers info links parameters request_bodies
-               responses schemas security_requirements security_schemes servers tags]
-          end.to_h { |key| [key, object_to_openapi(objects[key], version).presence] }
+            %i[callbacks examples headers links request_bodies servers]
+          end
+        ).index_with { |key| object_to_openapi(objects[key], version).presence }
 
         with_openapi_extensions(
-          if version.major == 2
+          if version == OpenAPI::V2_0
             openapi_server = objects[:servers].first || default_server
             uri = URI(openapi_server.url) if openapi_server
             {
@@ -290,7 +291,7 @@ module Jsapi
                 operation.consumes(self)
               end.uniq.sort.presence,
               produces: operations.flat_map do |operation|
-                operation.produces(self)
+                operation.produces(self).map(&:to_s)
               end.uniq.sort.presence,
               paths: openapi_paths,
               definitions: openapi_objects[:schemas],
@@ -301,12 +302,7 @@ module Jsapi
           else
             {
               # Order according to the OpenAPI specification 3.x
-              openapi:
-                case version.minor
-                when 0 then '3.0.3'
-                when 1 then '3.1.1'
-                when 2 then '3.2.0'
-                end,
+              openapi: version.to_s,
               info: openapi_objects[:info],
               servers:
                 openapi_objects[:servers] ||

data/lib/jsapi/meta/existence.rb

@@ -30,7 +30,9 @@ module Jsapi
       # or must be +false+.
       PRESENT = new(4)
 
-      # Creates a new instance from +value+.
+      # Transforms +value+ to an instance of this class.
+      #
+      # Raises an +ArgumentError+ if +value+ could not be transformed.
       def self.from(value)
         return value if value.is_a?(Existence)
 

data/lib/jsapi/meta/openapi/version.rb

@@ -6,9 +6,9 @@ module Jsapi
       class Version
         include Comparable
 
-        # Creates an \OpenAPI version from +version+.
+        # Transforms +version+ to an instance of this class.
         #
-        # Raises an +ArgumentError+ if +version+ isn`t supported.
+        # Raises an +ArgumentError+ if +version+ could not be transformed.
         def self.from(version)
           return version if version.is_a?(Version)
 
@@ -48,13 +48,25 @@ module Jsapi
           minor <=> other.minor
         end
 
-        def inspect
+        def inspect # :nodoc:
           "<#{self.class.name} #{self}>"
         end
 
         def to_s # :nodoc:
-          "#{major}.#{minor}"
+          @to_s ||=
+            case [major, minor]
+            when [3, 0]
+              '3.0.3'
+            when [3, 1]
+              '3.1.1'
+            when [3, 2]
+              '3.2.0'
+            else
+              "#{major}.#{minor}"
+            end
         end
+
+        alias as_json to_s
       end
     end
   end

data/lib/jsapi/meta/operation.rb

@@ -117,12 +117,12 @@ module Jsapi
         parent_path + path
       end
 
-      # Returns the MIME type consumed by the operation.
+      # Returns the media type consumed by the operation.
       def consumes(definitions)
         request_body&.resolve(definitions)&.content_type
       end
 
-      # Returns an array containing the MIME types produced by the operation.
+      # Returns an array containing the media types produced by the operation.
       def produces(definitions)
         responses.values.filter_map do |response|
           response.resolve(definitions).content_type
@@ -154,7 +154,7 @@ module Jsapi
               result[:consumes] = [consumes]
             end
             if (produces = produces(definitions)).present?
-              result[:produces] = produces
+              result[:produces] = produces.map(&:to_s)
             end
             result[:schemes] = schemes if schemes.present?
           elsif servers.present?

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

@@ -11,7 +11,7 @@ module Jsapi
 
         ##
         # :attr: content_type
-        # The content type used to describe complex parameters in \OpenAPI 3.0 and higher.
+        # The media type used to describe complex parameters in \OpenAPI 3.0 and higher.
         attribute :content_type, String
 
         ##

data/lib/jsapi/meta/pathname.rb

@@ -5,7 +5,7 @@ module Jsapi
     # Represents a relative path name.
     class Pathname
       class << self
-        # Creates a Pathname from +name+.
+        # Transforms +name+ to an instance of this class.
         def from(name)
           return name if name.is_a?(Pathname)
 
@@ -30,8 +30,8 @@ module Jsapi
 
       alias eql? ==
 
-      # Creates a new Pathname by appending +other+ to +self+.
-      # Returns +self+ if +other+ is nil.
+      # Creates a new Pathname by appending +other+ to itself.
+      # Returns itself if +other+ is nil.
       def +(other)
         return self if other.nil?
 

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

@@ -7,15 +7,12 @@ module Jsapi
       class Base < Model::Base
         include OpenAPI::Extensions
 
-        JSON_TYPE = %r{(^application/|^text/|\+)json$}.freeze # :nodoc:
-        JSON_SEQ_TYPE = 'application/json-seq' # :nodoc:
-
         delegate_missing_to :schema
 
         ##
         # :attr: content_type
-        # The content type, <code>"application/json"</code> by default.
-        attribute :content_type, String, default: 'application/json'
+        # The media type of the response, <code>"application/json"</code> by default.
+        attribute :content_type, Media::Type, default: Media::Type::APPLICATION_JSON
 
         ##
         # :attr: description
@@ -66,17 +63,6 @@ module Jsapi
           @schema = Schema.new(keywords)
         end
 
-        # Returns true if content type is a JSON MIME type as specified by
-        # https://mimesniff.spec.whatwg.org/#json-mime-type.
-        def json_type?
-          content_type.match?(JSON_TYPE)
-        end
-
-        # Returns true if content type is <code>"application/json-seq"</code>.
-        def json_seq_type?
-          content_type == JSON_SEQ_TYPE
-        end
-
         # Returns a hash representing the \OpenAPI response object.
         def to_openapi(version, definitions)
           version = OpenAPI::Version.from(version)
@@ -91,7 +77,7 @@ module Jsapi
                 end.compact.presence,
                 examples: (
                   if (example = examples.values.first).present?
-                    { content_type => example.resolve(definitions).value }
+                    { content_type.to_s => example.resolve(definitions).value }
                   end
                 )
               }
@@ -103,8 +89,9 @@ module Jsapi
                   header.to_openapi(version)
                 end.presence,
                 content: {
-                  content_type => {
-                    **if json_seq_type? && schema.array? && version >= OpenAPI::V3_2
+                  content_type.to_s => {
+                    **if content_type == Media::Type::APPLICATION_JSON_SEQ &&
+                      schema.array? && version >= OpenAPI::V3_2
                         { itemSchema: schema.items.to_openapi(version) }
                       else
                         { schema: schema.to_openapi(version) }

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

@@ -4,6 +4,7 @@ module Jsapi
   module Meta
     module Schema
       class Boundary
+        # Transforms +value+ to an instance of this class.
         def self.from(value)
           case value
           when Boundary

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 = '1.4'
+    VERSION = '1.4.1'
   end
 end

data/lib/jsapi.rb

@@ -4,6 +4,7 @@ require 'jsapi/invalid_value_helper'
 require 'jsapi/invalid_value_error'
 require 'jsapi/invalid_argument_error'
 require 'jsapi/configuration'
+require 'jsapi/media'
 require 'jsapi/model'
 require 'jsapi/meta'
 require 'jsapi/dsl'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsapi
 version: !ruby/object:Gem::Version
-  version: '1.4'
+  version: 1.4.1
 platform: ruby
 authors:
 - Denis Göller
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-15 00:00:00.000000000 Z
+date: 2025-11-23 00:00:00.000000000 Z
 dependencies: []
 description:
 email: denis@dmgoeller.de
@@ -50,6 +50,10 @@ files:
 - lib/jsapi/json/object.rb
 - lib/jsapi/json/string.rb
 - lib/jsapi/json/value.rb
+- lib/jsapi/media.rb
+- lib/jsapi/media/range.rb
+- lib/jsapi/media/type.rb
+- lib/jsapi/media/type_and_subtype.rb
 - lib/jsapi/meta.rb
 - lib/jsapi/meta/callable.rb
 - lib/jsapi/meta/callable/symbol_evaluator.rb