jsapi 1.3 → 1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2abec73a53f67bfebe51e0466e662be1dfc393f3fe5946612a12c94fde8b463b
-  data.tar.gz: f9c69c6df40d4f88e5175beb185a528ad76f2c6b4cbf6a8f88ac15915943f706
+  metadata.gz: 87f305e41facfb84c96e5e2406b636aa9e10a27545a25d42a5029f4d4dd93488
+  data.tar.gz: 6723179cd4981c590a4e8f0c45808d9b69a0436be48e1e89f06c7ef0a4b56ddb
 SHA512:
-  metadata.gz: ca369ab50a38016fa37e9199e5a38f9248d2cbcfa51d80c39461dd206d8b09fb6ae60ea29861d211b9a939e408b6e48f35008da577c9f3a789bb6ebb592fafda
-  data.tar.gz: 8093446b1d7601d9a0e89cae395fa0ced837901b1a9eb0866ebcfd721cebb9e07d611c851735c847a699d71cec4ca474d04e39710ebc244476f6deb635e7fdc7
+  metadata.gz: 7ddefbaaa678ed70e29055dbe4452ee0f4f738fa2386e8e3f5dbaa42e682ca973fa0bd04e5c6b22b2570bfd290fd4fcfbb42c8f7e50650ffda50d0cfbb160cc7
+  data.tar.gz: 3fc210ea9c236f319f1c94dcb741d7d910eb7edb90020aafcbbee2a033bd232a9bb88dd26fc306869f7c3be715487f4655a517e5968f63461a6bbad57074099a

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/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,11 +253,18 @@ 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_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 =
           if version.major == 2
@@ -252,7 +284,7 @@ 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)
@@ -300,6 +332,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 +408,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 +434,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 +445,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/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/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,6 +112,11 @@ module Jsapi
         (@parameters ||= {})[name.to_s] = Parameter.new(name, keywords)
       end
 
+      # Returns the full path of the operation as a Pathname.
+      def full_path
+        parent_path + path
+      end
+
       # Returns the MIME type consumed by the operation.
       def consumes(definitions)
         request_body&.resolve(definitions)&.content_type
@@ -116,6 +129,13 @@ module Jsapi
         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)

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
+        # Creates a Pathname from +name+.
+        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 +self+.
+      # Returns +self+ 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.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'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsapi
 version: !ruby/object:Gem::Version
-  version: '1.3'
+  version: '1.4'
 platform: ruby
 authors:
 - Denis Göller
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-02 00:00:00.000000000 Z
+date: 2025-11-15 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
@@ -86,6 +87,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