jsapi 1.3 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2abec73a53f67bfebe51e0466e662be1dfc393f3fe5946612a12c94fde8b463b
-  data.tar.gz: f9c69c6df40d4f88e5175beb185a528ad76f2c6b4cbf6a8f88ac15915943f706
+  metadata.gz: 7651bda7e379186840e78ede1870f022b69deca559b6ba5ad6d0cbc8aac5c840
+  data.tar.gz: 16a661d4c24e1195f23d6fa0a23d27ba53fb944819b2f9a57c2174456f5ca913
 SHA512:
-  metadata.gz: ca369ab50a38016fa37e9199e5a38f9248d2cbcfa51d80c39461dd206d8b09fb6ae60ea29861d211b9a939e408b6e48f35008da577c9f3a789bb6ebb592fafda
-  data.tar.gz: 8093446b1d7601d9a0e89cae395fa0ced837901b1a9eb0866ebcfd721cebb9e07d611c851735c847a699d71cec4ca474d04e39710ebc244476f6deb635e7fdc7
+  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/controller/parameters.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'cgi'
-
 module Jsapi
   module Controller
     # Used to wrap request parameters.
@@ -24,9 +22,7 @@ module Jsapi
         @raw_attributes = {}
 
         # Parameters
-        operation.parameters.each do |name, parameter_model|
-          parameter_model = parameter_model.resolve(definitions)
-
+        operation.resolved_parameters(definitions).each do |name, parameter_model|
           @raw_attributes[name] = JSON.wrap(
             case parameter_model.in
             when 'header'

data/lib/jsapi/dsl/class_methods.rb

@@ -147,6 +147,17 @@ module Jsapi
         api_definitions { parameter(name, **keywords, &block) }
       end
 
+      # Groups operations by path.
+      #
+      #   api_path 'api' do
+      #     operation 'foo'
+      #     operation 'bar'
+      #   end
+      #
+      def api_path(name, &block)
+        api_definitions { path(name, &block) }
+      end
+
       # Defines a reusable request body.
       #
       #   api_request_body 'foo', type: 'string'

data/lib/jsapi/dsl/definitions.rb

@@ -155,6 +155,20 @@ module Jsapi
         end
       end
 
+      # Groups operations by path.
+      #
+      #   path 'api' do
+      #     operation 'foo'
+      #     operation 'bar'
+      #   end
+      #
+      def path(name = nil, &block)
+        define('path', name&.inspect) do
+          path_model = @meta_model.add_path(name)
+          Path.new(path_model, &block) if block
+        end
+      end
+
       # Specifies a reusable request body.
       #
       #   request_body 'foo', type: 'string'

data/lib/jsapi/dsl/path.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module DSL
+    class Path < Base
+      # Specifies an operation within the current path.
+      #
+      #   operation 'foo' do
+      #     parameter 'bar', type: 'string'
+      #     response do
+      #       property 'foo', type: 'string'
+      #     end
+      #   end
+      #
+      def operation(name = nil, **keywords, &block)
+        define('operation', name&.inspect) do
+          operation_model = @meta_model.owner.add_operation(name, @meta_model.name, keywords)
+          Operation.new(operation_model, &block) if block
+        end
+      end
+
+      # Specifies a parameter applicable for all operations in this path.
+      #
+      #   parameter 'foo', type: 'string'
+      #
+      # See Meta::Path#parameters for further information.
+      def parameter(name, **keywords, &block)
+        define('parameter', name.inspect) do
+          parameter_model = @meta_model.add_parameter(name, keywords)
+          Parameter.new(parameter_model, &block) if block
+        end
+      end
+
+      # Specifies a nested path.
+      def path(name = nil, &block)
+        define('path', name&.inspect) do
+          path_model = @meta_model.owner.add_path(@meta_model.name + name.to_s)
+          Path.new(path_model, &block) if block
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/dsl.rb

@@ -9,6 +9,7 @@ require_relative 'dsl/request_body'
 require_relative 'dsl/response'
 require_relative 'dsl/callback'
 require_relative 'dsl/operation'
+require_relative 'dsl/path'
 require_relative 'dsl/definitions'
 require_relative 'dsl/class_methods'
 

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

@@ -8,7 +8,7 @@ module Jsapi
       ##
       # :attr: base_path
       # The base path of the API. Applies to \OpenAPI 2.0.
-      attribute :base_path, String
+      attribute :base_path, Pathname
 
       ##
       # :attr: callbacks
@@ -65,6 +65,11 @@ module Jsapi
       # The reusable Parameter objects.
       attribute :parameters, { String => Parameter }, accessors: %i[reader writer]
 
+      ##
+      # :attr: paths
+      # The Path objects.
+      attribute :paths, { Pathname => Path }, accessors: %i[reader writer]
+
       ##
       # :attr: rescue_handlers
       # The RescueHandler objects.
@@ -138,15 +143,27 @@ module Jsapi
         @parent&.inherited(self)
       end
 
-      def add_operation(name = nil, keywords = {}) # :nodoc:
+      def add_operation(name, parent_path = nil, keywords = {}) # :nodoc:
+        parent_path, keywords = nil, parent_path if parent_path.is_a?(Hash)
+
         name = name.nil? ? default_operation_name : name.to_s
-        keywords = keywords.reverse_merge(path: default_operation_path)
-        (@operations ||= {})[name] = Operation.new(name, keywords)
+        parent_path ||= default_operation_name unless keywords[:path].present?
+
+        (@operations ||= {})[name] = Operation.new(name, parent_path, keywords)
       end
 
       def add_parameter(name, keywords = {}) # :nodoc:
         name = name.to_s
-        (@parameters ||= {})[name] = Parameter.new(name, keywords)
+
+        Parameter.new(name, keywords).tap do |parameter|
+          (@parameters ||= {})[name] = parameter
+          attribute_changed(:parameters)
+        end
+      end
+
+      def add_path(name, keywords = {}) # :nodoc:
+        pathname = Pathname.from(name)
+        (@paths ||= {})[pathname] ||= Path.new(pathname, self, keywords)
       end
 
       # Returns an array containing itself and all of the +Definitions+ instances
@@ -207,6 +224,14 @@ module Jsapi
         self
       end
 
+      # Resets the memoized parameters for the given path.
+      def invalidate_path_parameters(pathname)
+        pathname = Pathname.from(pathname)
+
+        @path_parameters&.delete(pathname)
+        each_descendant { |descendant| descendant.invalidate_path_parameters(pathname) }
+      end
+
       # Returns a hash representing the \JSON \Schema document for +name+.
       def json_schema_document(name)
         find_schema(name)&.to_json_schema&.tap do |json_schema_document|
@@ -228,23 +253,31 @@ module Jsapi
         version = OpenAPI::Version.from(version)
         operations = objects[:operations].values
 
-        openapi_paths =
-          operations.group_by { |operation| operation.path || default_operation_path }
-                    .transform_values do |operations_by_path|
-            OpenAPI::PathItem.new(operations_by_path).to_openapi(version, self)
-          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_paths = operations.group_by(&:full_path).to_h do |key, value|
+          [
+            key.to_s,
+            OpenAPI::PathItem.new(
+              value,
+              description: path_description(key),
+              parameters: path_parameters(key),
+              summary: path_summary(key),
+              servers: path_servers(key)
+            ).to_openapi(version, self)
+          ]
+        end.presence
+
+        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
             {
@@ -252,13 +285,13 @@ module Jsapi
               swagger: '2.0',
               info: openapi_objects[:info],
               host: openapi_objects[:host] || uri&.hostname,
-              basePath: openapi_objects[:base_path] || uri&.path,
+              basePath: openapi_objects[:base_path]&.to_s || uri&.path,
               schemes: openapi_objects[:schemes] || Array(uri&.scheme).presence,
               consumes: operations.filter_map do |operation|
                 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],
@@ -269,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] ||
@@ -300,6 +328,44 @@ module Jsapi
         )
       end
 
+      ##
+      # :method: path_description
+      # :args: pathname
+      # Returns the most accurate description for the given path.
+
+      ##
+      # :method: path_servers
+      # :args: pathname
+      # Returns the most accurate Server objects for the given path.
+
+      ##
+      # :method: path_summary
+      # :args: pathname
+      # Returns the most accurate summary for the given path.
+
+      %i[description servers summary].each do |name|
+        define_method(:"path_#{name}") do |arg|
+          Pathname.from(arg).ancestors.each do |pathname|
+            ancestors.each do |ancestor|
+              value = ancestor.path(pathname)&.public_send(name)
+              return value if value.present?
+            end
+          end
+          nil
+        end
+      end
+
+      # Returns a hash containing the Parameter objects that are applicable to all
+      # operations in the given path.
+      # :args: pathname
+      def path_parameters(arg)
+        arg = Pathname.from(arg || '')
+
+        (@path_parameters ||= {})[arg] ||= arg.ancestors.flat_map do |pathname|
+          ancestors.filter_map { |ancestor| ancestor.path(pathname)&.parameters }
+        end.reduce(&:reverse_merge) || {}
+      end
+
       # Returns the first RescueHandler to handle +exception+, or nil if no one could be found.
       def rescue_handler_for(exception)
         objects[:rescue_handlers].find { |r| r.match?(exception) }
@@ -338,15 +404,14 @@ module Jsapi
       def invalidate_ancestors
         @ancestors = nil
         @objects = nil
-        @children&.each(&:invalidate_ancestors)
-        @dependent_definitions&.each(&:invalidate_ancestors)
+        @path_parameters = nil
+        each_descendant(&:invalidate_ancestors)
       end
 
       # Invalidates cached objects.
       def invalidate_objects
         @objects = nil
-        @children&.each(&:invalidate_objects)
-        @dependent_definitions&.each(&:invalidate_objects)
+        each_descendant(&:invalidate_objects)
       end
 
       private
@@ -365,10 +430,6 @@ module Jsapi
           end
       end
 
-      def default_operation_path
-        @default_operation_path ||= "/#{default_operation_name}"
-      end
-
       def default_server
         @default_server ||=
           if (name = @owner.try(:name))
@@ -380,6 +441,11 @@ module Jsapi
           end
       end
 
+      def each_descendant(&block)
+        [*@children, *dependent_definitions].each(&block)
+        nil
+      end
+
       def objects
         @objects ||= ancestors.each_with_object({}) do |ancestor, objects|
           self.class.attribute_names.each do |key|

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/path_item.rb

@@ -4,15 +4,25 @@ module Jsapi
   module Meta
     module OpenAPI
       class PathItem # :nodoc:
-        def initialize(operations)
+        def initialize(operations, keywords = {})
           @operations = operations
+          @summary = keywords[:summary]
+          @description = keywords[:description]
+          @servers = keywords[:servers]
+          @parameters = keywords[:parameters]
         end
 
         def to_openapi(version, definitions)
           version = OpenAPI::Version.from(version)
 
           {}.tap do |fields|
-            @operations.each do |operation|
+            if version >= OpenAPI::V3_0
+              fields[:summary] = @summary if @summary.present?
+              fields[:description] = @description if @description.present?
+            end
+
+            # Operations
+            @operations&.each do |operation|
               method = operation.method
               standardized_method = method.downcase
 
@@ -23,6 +33,18 @@ module Jsapi
                 additional_operations[method] = operation.to_openapi(version, definitions)
               end
             end
+
+            # Servers
+            if version >= OpenAPI::V3_0 && @servers.present?
+              fields[:servers] = @servers.map { |server| server.to_openapi(version) }
+            end
+
+            # Parameters
+            if @parameters.present?
+              fields[:parameters] = @parameters.values.map do |parameter|
+                parameter.to_openapi(version, definitions)
+              end
+            end
           end
         end
 

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

@@ -46,10 +46,15 @@ module Jsapi
       # The parameters of the operation.
       attribute :parameters, { String => Parameter }, accessors: %i[reader writer]
 
+      ##
+      # :attr_reader: parent_path
+      # The parent path as a Pathname.
+      attribute :parent_path, Pathname, accessors: %i[reader]
+
       ##
       # :attr: path
-      # The relative path of the operation.
-      attribute :path, String
+      # The relative path of the operation as a Pathname.
+      attribute :path, Pathname
 
       ##
       # :attr: request_body
@@ -95,8 +100,11 @@ module Jsapi
       # The tags used to group operations in an \OpenAPI document.
       attribute :tags, [String]
 
-      def initialize(name = nil, keywords = {})
+      def initialize(name, parent_path = nil, keywords = {})
+        parent_path, keywords = nil, parent_path if parent_path.is_a?(Hash)
+
         @name = name&.to_s
+        @parent_path = Pathname.from(parent_path)
         super(keywords)
       end
 
@@ -104,18 +112,30 @@ module Jsapi
         (@parameters ||= {})[name.to_s] = Parameter.new(name, keywords)
       end
 
-      # Returns the MIME type consumed by the operation.
+      # Returns the full path of the operation as a Pathname.
+      def full_path
+        parent_path + path
+      end
+
+      # 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
         end.uniq.sort
       end
 
+      # Merges the parameters of this operation and the common parameters of all
+      # parent pathes and resolves them.
+      def resolved_parameters(definitions)
+        (definitions.path_parameters(full_path).presence&.merge(parameters) || parameters)
+          .transform_values { |parameter| parameter.resolve(definitions) }
+      end
+
       # Returns a hash representing the \OpenAPI operation object.
       def to_openapi(version, definitions)
         version = OpenAPI::Version.from(version)
@@ -134,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/path.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # Specifies a path.
+    class Path < Model::Base
+      ##
+      # :attr: description
+      # The description that applies to all operations in this path.
+      # Applies to \OpenAPI 3.0 and higher.
+      attribute :description, String
+
+      ##
+      # :attr_reader: name
+      # The relative path as a Pathname.
+      attribute :name, Pathname, accessors: %i[reader]
+
+      ##
+      # :attr: parameters
+      # The Parameter objects applicable for all operations in this path.
+      attribute :parameters, { String => Parameter }, accessors: %i[reader writer]
+
+      ##
+      # :attr_reader: owner
+      attribute :owner, accessors: %i[reader]
+
+      ##
+      # :attr: summary
+      # The summary that applies to all operations in this path.
+      # Applies to \OpenAPI 3.0 and higher.
+      attribute :summary, String
+
+      ##
+      # :attr: servers
+      # The Server objects that applies to all operations in this path.
+      # Applies to \OpenAPI 3.0 and higher.
+      attribute :servers, [Server]
+
+      # Creates a new path with the given name and owner.
+      def initialize(name, owner, keywords = {})
+        @name = Pathname.from(name)
+        @owner = owner
+        super(keywords)
+      end
+
+      def add_parameter(name, keywords = {}) # :nodoc:
+        name = name.to_s
+
+        Parameter.new(name, keywords).tap do |parameter|
+          (@parameters ||= {})[name] = parameter
+          @owner.try(:invalidate_path_parameters, self.name)
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/pathname.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # Represents a relative path name.
+    class Pathname
+      class << self
+        # Transforms +name+ to an instance of this class.
+        def from(name)
+          return name if name.is_a?(Pathname)
+
+          name.nil? ? new : new(name)
+        end
+      end
+
+      attr_reader :segments
+
+      delegate :hash, to: :segments
+
+      def initialize(*segments) # :nodoc:
+        @segments = segments.flat_map do |segment|
+          segment = segment.to_s.delete_prefix('/')
+          segment.present? ? segment.split('/', -1) : ''
+        end
+      end
+
+      def ==(other) # :nodoc:
+        other.is_a?(Pathname) && segments == other.segments
+      end
+
+      alias eql? ==
+
+      # Creates a new Pathname by appending +other+ to itself.
+      # Returns itself if +other+ is nil.
+      def +(other)
+        return self if other.nil?
+
+        Pathname.new(*@segments, *Pathname.from(other).segments)
+      end
+
+      # Returns an array containing itself and all parent pathnames.
+      def ancestors
+        @ancestors ||= @segments.count.downto(0).map do |i|
+          Pathname.new(*@segments[0, i])
+        end
+      end
+
+      def inspect # :nodoc:
+        "#<#{self.class} #{to_s.inspect}>"
+      end
+
+      # Returns the relative path name as a string.
+      def to_s
+        @to_s ||= @segments.presence&.each_with_index&.map do |segment, index|
+          index.zero? && segment.blank? ? '//' : "/#{segment}"
+        end&.join || '/'
+      end
+    end
+  end
+end

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/meta.rb

@@ -24,6 +24,8 @@ require_relative 'meta/property'
 require_relative 'meta/schema'
 require_relative 'meta/request_body'
 require_relative 'meta/parameter'
+require_relative 'meta/pathname'
+require_relative 'meta/path'
 require_relative 'meta/response'
 require_relative 'meta/operation'
 require_relative 'meta/rescue_handler'

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.3'
+    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.3'
+  version: 1.4.1
 platform: ruby
 authors:
 - Denis Göller
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-02 00:00:00.000000000 Z
+date: 2025-11-23 00:00:00.000000000 Z
 dependencies: []
 description:
 email: denis@dmgoeller.de
@@ -34,6 +34,7 @@ files:
 - lib/jsapi/dsl/examples.rb
 - lib/jsapi/dsl/operation.rb
 - lib/jsapi/dsl/parameter.rb
+- lib/jsapi/dsl/path.rb
 - lib/jsapi/dsl/request_body.rb
 - lib/jsapi/dsl/response.rb
 - lib/jsapi/dsl/schema.rb
@@ -49,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
@@ -86,6 +91,8 @@ files:
 - lib/jsapi/meta/parameter.rb
 - lib/jsapi/meta/parameter/base.rb
 - lib/jsapi/meta/parameter/reference.rb
+- lib/jsapi/meta/path.rb
+- lib/jsapi/meta/pathname.rb
 - lib/jsapi/meta/property.rb
 - lib/jsapi/meta/reference_error.rb
 - lib/jsapi/meta/request_body.rb