jsapi 1.2 → 1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40ceeb6c8774b09bfb3fbfe2bc4550444a179158b43cac27d6f9923cead5971c
-  data.tar.gz: f6cc387571c73b93cdcc121c1c46267424a46362f4c400dee8bd53ec2e0af561
+  metadata.gz: 87f305e41facfb84c96e5e2406b636aa9e10a27545a25d42a5029f4d4dd93488
+  data.tar.gz: 6723179cd4981c590a4e8f0c45808d9b69a0436be48e1e89f06c7ef0a4b56ddb
 SHA512:
-  metadata.gz: 437497757705da6bfeddab26b70ab0e4df3b7abe11f78b4433f6b5576b783f8d576c0c3b2e6612b4e941d58136e965b705e5db37176f59ee672c58bf64e5bb42
-  data.tar.gz: d25820eec66069cba5bb25eb2a0c1cb262835a57ec60eef94199ab247332aa296ba5228ebf0a61c1bbc80c9b350aa19cfd2339cb11188c260973f3607cd6da5f
+  metadata.gz: 7ddefbaaa678ed70e29055dbe4452ee0f4f738fa2386e8e3f5dbaa42e682ca973fa0bd04e5c6b22b2570bfd290fd4fcfbb42c8f7e50650ffda50d0cfbb160cc7
+  data.tar.gz: 3fc210ea9c236f319f1c94dcb741d7d910eb7edb90020aafcbbee2a033bd232a9bb88dd26fc306869f7c3be715487f4655a517e5968f63461a6bbad57074099a

data/lib/jsapi/configuration.rb

@@ -4,11 +4,11 @@ module Jsapi
   # Holds the \Jsapi configuration.
   class Configuration
     # The path where the API definitions are located relative to +Rails.root+.
-    # The default is <code>"app/api_defs"</code>.
+    # The default is <code>"jsapi/api_defs"</code>.
     attr_accessor :api_defs_path
 
     def initialize # :nodoc:
-      @api_defs_path = 'app/api_defs'
+      @api_defs_path = 'jsapi/api_defs'
     end
 
     # Returns the absolute +Pathname+ for +args+ within +api_defs_path+.

data/lib/jsapi/controller/methods.rb

@@ -15,7 +15,9 @@ module Jsapi
       # 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.
+      # 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.
       #
       #   api_operation('foo') do |api_params|
       #     # ...
@@ -153,18 +155,29 @@ module Jsapi
         end
 
         # Write response
-        return unless response_model.json_type?
+        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
-        render(json: response, status: status)
+
+        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(
           Parameters.new(
             params.except(:action, :controller, :format).permit!,
-            request.headers,
+            request,
             operation,
             definitions,
             strong: strong

data/lib/jsapi/controller/parameters.rb

@@ -14,18 +14,30 @@ module Jsapi
       # If +strong+ is true+ parameters that can be mapped are accepted only. That means that
       # the instance created is invalid if +params+ contains any parameters that can't be
       # mapped to a parameter or a request body property of +operation+.
-      def initialize(params, headers, operation, definitions, strong: false)
-        @params = params.to_h
-        @strong = strong == true
+      def initialize(params, request, operation, definitions, strong: false)
+        params = params.to_h
+        unassigned_params = params.dup
+
+        @params_to_be_validated = strong == true ? params.dup : {}
         @raw_attributes = {}
-        @raw_additional_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(
-            parameter_model.in == 'header' ? headers[name] : @params[name],
+            case parameter_model.in
+            when 'header'
+              request.headers[name]
+            when 'querystring'
+              query_params = request.query_parameters
+              keys = query_params.keys
+
+              unassigned_params.except!(*keys)
+              @params_to_be_validated.except!(*keys)
+
+              parameter_model.object? ? params.slice(*keys) : query_params.to_query
+            else
+              unassigned_params.delete(name)
+            end,
             parameter_model.schema.resolve(definitions),
             definitions,
             context: :request
@@ -37,23 +49,24 @@ module Jsapi
                                        &.schema&.resolve(definitions)
         if request_body_schema&.object?
           request_body = JSON.wrap(
-            @params.except(*operation.parameters.keys),
+            unassigned_params,
             request_body_schema,
             definitions,
             context: :request
           )
           @raw_attributes.merge!(request_body.raw_attributes)
           @raw_additional_attributes = request_body.raw_additional_attributes
+          @params_to_be_validated.except!(*@raw_additional_attributes.keys)
+        else
+          @raw_additional_attributes = {}
         end
       end
 
       # Validates the request parameters. Returns true if the parameters are valid, false
       # otherwise. Detected errors are added to +errors+.
       def validate(errors)
-        [
-          validate_attributes(errors),
-          !@strong || validate_parameters(@params, attributes, errors)
-        ].all?
+        validate_attributes(errors) &&
+          validate_parameters(@params_to_be_validated, attributes, errors)
       end
 
       private

data/lib/jsapi/controller/response.rb

@@ -50,11 +50,27 @@ module Jsapi
       # Returns the \JSON representation of the response as a string.
       def to_json(*)
         schema = @response.schema.resolve(@definitions)
-        if @response.locale
-          I18n.with_locale(@response.locale) { jsonify(@object, schema) }
-        else
-          jsonify(@object, schema)
-        end.to_json
+        with_locale { jsonify(@object, schema) }.to_json
+      end
+
+      # Writes the response in \JSON sequence text format to +stream+.
+      def write_json_seq_to(stream)
+        schema = @response.schema.resolve(@definitions)
+        with_locale do
+          items, item_schema =
+            if schema.array? && @object.respond_to?(:each)
+              [@object, schema.items.resolve(@definitions)]
+            else
+              [[@object], schema]
+            end
+
+          items.each do |item|
+            stream.write("\u001E") # Record separator (see RFC 7464)
+            stream.write(jsonify(item, item_schema).to_json)
+            stream.write("\n")
+          end
+        end
+        nil
       end
 
       private
@@ -138,6 +154,14 @@ module Jsapi
 
         properties.presence
       end
+
+      def with_locale(&block)
+        if @response.locale
+          I18n.with_locale(@response.locale, &block)
+        else
+          yield
+        end
+      end
     end
   end
 end

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/callback/base.rb

@@ -23,7 +23,7 @@ module Jsapi
         # Returns a hash representing the \OpenAPI callback object.
         def to_openapi(version, definitions)
           operations.transform_values do |operation|
-            { operation.method => operation.to_openapi(version, definitions) }
+            OpenAPI::PathItem.new([operation]).to_openapi(version, definitions)
           end
         end
       end

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,13 +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|
-            operations_by_path.index_by(&:method).transform_values do |operation|
-              operation.to_openapi(version, self)
-            end
-          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
@@ -254,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)
@@ -271,10 +301,16 @@ module Jsapi
           else
             {
               # Order according to the OpenAPI specification 3.x
-              openapi: version.minor.zero? ? '3.0.3' : '3.1.1',
+              openapi:
+                case version.minor
+                when 0 then '3.0.3'
+                when 1 then '3.1.1'
+                when 2 then '3.2.0'
+                end,
               info: openapi_objects[:info],
-              servers: openapi_objects[:servers] ||
-                [default_server&.to_openapi].compact.presence,
+              servers:
+                openapi_objects[:servers] ||
+                [default_server&.to_openapi(version)].compact.presence,
               paths: openapi_paths,
               components: {
                 schemas: openapi_objects[:schemas],
@@ -296,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) }
@@ -334,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
@@ -361,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))
@@ -376,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/example/base.rb

@@ -29,13 +29,11 @@ module Jsapi
 
         # Returns a hash representing the \OpenAPI example object.
         def to_openapi(*)
-          with_openapi_extensions(summary: summary, description: description).tap do |result|
-            if external?
-              result[:external_value] = value
-            else
-              result[:value] = value
+          with_openapi_extensions(
+            { summary: summary, description: description }.tap do |result|
+              result[external? ? :externalValue : :value] = value
             end
-          end
+          )
         end
       end
     end

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

@@ -33,13 +33,15 @@ module Jsapi
         attribute :server, Server
 
         # Returns a hash representing the \OpenAPI link object.
-        def to_openapi(*)
+        def to_openapi(version, *)
+          version = OpenAPI::Version.from(version)
+
           with_openapi_extensions(
             operationId: operation_id,
             parameters: parameters.presence,
             requestBody: request_body,
             description: description,
-            server: server&.to_openapi
+            server: server&.to_openapi(version)
           )
         end
       end

data/lib/jsapi/meta/oauth_flow.rb

@@ -18,12 +18,20 @@ module Jsapi
       # The authorization URL to be used for the flow.
       attribute :authorization_url, String
 
+      ##
+      # :attr: device_authorization_url
+      # The device authorization URL to be used for the flow.
+      #
+      # Note that the device authorization URL was introduced with \OpenAPI 3.2.
+      # It is omitted when generating an \OpenAPI document with a lower version.
+      attribute :device_authorization_url, String
+
       ##
       # :attr: refresh_url
       # The refresh URL to be used for the flow.
       #
       # Note that the refresh URL was introduced with \OpenAPI 3.0. It is
-      # skipped when generating an \OpenAPI 2.0 document.
+      # omitted when generating an \OpenAPI document with a lower version.
       attribute :refresh_url, String
 
       ##
@@ -42,8 +50,9 @@ module Jsapi
 
         with_openapi_extensions(
           authorizationUrl: authorization_url,
+          deviceAuthorizationUrl: (device_authorization_url if version >= OpenAPI::V3_2),
           tokenUrl: token_url,
-          refreshUrl: (refresh_url if version.major > 2),
+          refreshUrl: (refresh_url if version >= OpenAPI::V3_0),
           scopes: scopes.transform_values(&:description)
         )
       end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      class PathItem # :nodoc:
+        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|
+            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
+
+              if standard_method?(standardized_method, version)
+                fields[standardized_method] = operation.to_openapi(version, definitions)
+              elsif version >= OpenAPI::V3_2
+                additional_operations = fields[:additionalOperations] ||= {}
+                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
+
+        private
+
+        def standard_method?(method, version)
+          case method
+          when 'delete', 'get', 'head', 'options', 'patch', 'post', 'put'
+            true
+          when 'trace'
+            version >= OpenAPI::V3_0
+          when 'query'
+            version >= OpenAPI::V3_2
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -19,6 +19,8 @@ module Jsapi
             new(3, 0)
           when '3.1'
             new(3, 1)
+          when '3.2'
+            new(3, 2)
           else
             raise ArgumentError, "unsupported OpenAPI version: #{version.inspect}"
           end
@@ -46,6 +48,10 @@ module Jsapi
           minor <=> other.minor
         end
 
+        def inspect
+          "<#{self.class.name} #{self}>"
+        end
+
         def to_s # :nodoc:
           "#{major}.#{minor}"
         end

data/lib/jsapi/meta/openapi.rb

@@ -2,6 +2,7 @@
 
 require_relative 'openapi/extensions'
 require_relative 'openapi/version'
+require_relative 'openapi/path_item'
 
 module Jsapi
   module Meta
@@ -9,6 +10,7 @@ module Jsapi
       V2_0 = Version.new(2, 0)
       V3_0 = Version.new(3, 0)
       V3_1 = Version.new(3, 1)
+      V3_2 = Version.new(3, 2)
     end
   end
 end