jsapi 1.2 → 1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40ceeb6c8774b09bfb3fbfe2bc4550444a179158b43cac27d6f9923cead5971c
-  data.tar.gz: f6cc387571c73b93cdcc121c1c46267424a46362f4c400dee8bd53ec2e0af561
+  metadata.gz: 2abec73a53f67bfebe51e0466e662be1dfc393f3fe5946612a12c94fde8b463b
+  data.tar.gz: f9c69c6df40d4f88e5175beb185a528ad76f2c6b4cbf6a8f88ac15915943f706
 SHA512:
-  metadata.gz: 437497757705da6bfeddab26b70ab0e4df3b7abe11f78b4433f6b5576b783f8d576c0c3b2e6612b4e941d58136e965b705e5db37176f59ee672c58bf64e5bb42
-  data.tar.gz: d25820eec66069cba5bb25eb2a0c1cb262835a57ec60eef94199ab247332aa296ba5228ebf0a61c1bbc80c9b350aa19cfd2339cb11188c260973f3607cd6da5f
+  metadata.gz: ca369ab50a38016fa37e9199e5a38f9248d2cbcfa51d80c39461dd206d8b09fb6ae60ea29861d211b9a939e408b6e48f35008da577c9f3a789bb6ebb592fafda
+  data.tar.gz: 8093446b1d7601d9a0e89cae395fa0ced837901b1a9eb0866ebcfd721cebb9e07d611c851735c847a699d71cec4ca474d04e39710ebc244476f6deb635e7fdc7

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'cgi'
+
 module Jsapi
   module Controller
     # Used to wrap request parameters.
@@ -14,18 +16,32 @@ 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)
 
           @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 +53,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/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

@@ -231,9 +231,7 @@ module Jsapi
         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
+            OpenAPI::PathItem.new(operations_by_path).to_openapi(version, self)
           end.presence
 
         openapi_objects =
@@ -271,10 +269,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],

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,46 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      class PathItem # :nodoc:
+        def initialize(operations)
+          @operations = operations
+        end
+
+        def to_openapi(version, definitions)
+          version = OpenAPI::Version.from(version)
+
+          {}.tap do |fields|
+            @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
+          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

data/lib/jsapi/meta/operation.rb

@@ -28,18 +28,8 @@ module Jsapi
 
       ##
       # :attr: method
-      # The HTTP verb of the operation. Possible values are:
-      #
-      # - <code>"delete"</code>
-      # - <code>"get"</code>
-      # - <code>"head"</code>
-      # - <code>"options"</code>
-      # - <code>"patch"</code>
-      # - <code>"post"</code>
-      # - <code>"put"</code>
-      #
-      # The default HTTP verb is <code>"get"</code>.
-      attribute :method, values: %w[delete get head options patch post put], default: 'get'
+      # The HTTP method of the operation, <code>"get"</code> by default.
+      attribute :method, String, default: 'get'
 
       ##
       # :attr: model
@@ -97,7 +87,7 @@ module Jsapi
 
       ##
       # :attr: summary
-      # The short summary of the operation.
+      # The short description of the operation.
       attribute :summary, String
 
       ##
@@ -148,7 +138,9 @@ module Jsapi
             end
             result[:schemes] = schemes if schemes.present?
           elsif servers.present?
-            result[:servers] = servers.map(&:to_openapi)
+            result[:servers] = servers.map do |server|
+              server.to_openapi(version)
+            end
           end
           # Parameters (and request body)
           result[:parameters] = parameters.values.flat_map do |parameter|

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

@@ -9,6 +9,11 @@ module Jsapi
 
         delegate_missing_to :schema
 
+        ##
+        # :attr: content_type
+        # The content type used to describe complex parameters in \OpenAPI 3.0 and higher.
+        attribute :content_type, String
+
         ##
         # :attr: deprecated
         # Specifies whether or not the parameter is deprecated.
@@ -31,9 +36,10 @@ module Jsapi
         # - <code>"header"</code>
         # - <code>"path"</code>
         # - <code>"query"</code>
+        # - <code>"querystring"</code>
         #
         # The default location is <code>"query"</code>.
-        attribute :in, String, values: %w[header path query], default: 'query'
+        attribute :in, String, values: %w[header path query querystring], default: 'query'
 
         ##
         # :attr_reader: name
@@ -54,8 +60,16 @@ module Jsapi
           @name = name.to_s
 
           keywords = keywords.dup
-          super(keywords.extract!(:deprecated, :description, :examples, :in, :openapi_extensions))
-
+          super(
+            keywords.extract!(
+              :content_type,
+              :deprecated,
+              :description,
+              :examples,
+              :in,
+              :openapi_extensions
+            )
+          )
           add_example(value: keywords.delete(:example)) if keywords.key?(:example)
           keywords[:ref] = keywords.delete(:schema) if keywords.key?(:schema)
 
@@ -75,12 +89,13 @@ module Jsapi
         # Returns a hash representing the \OpenAPI parameter object.
         def to_openapi(version, definitions)
           version = OpenAPI::Version.from(version)
-          schema = self.schema.resolve(definitions)
 
-          openapi_parameter(
+          openapi_parameter_object(
             name,
-            schema,
+            schema.resolve(definitions),
             version,
+            location: self.in,
+            content_type: content_type || ('text/plain' if self.in == 'querystring'),
             description: description,
             required: required?,
             deprecated: deprecated?,
@@ -92,39 +107,30 @@ module Jsapi
         # Returns an array of hashes representing the \OpenAPI parameter objects.
         def to_openapi_parameters(version, definitions)
           version = OpenAPI::Version.from(version)
+          is_querystring = self.in == 'querystring'
           schema = self.schema.resolve(definitions)
 
-          if schema.object?
+          if schema.object? && (version < OpenAPI::V3_2 || !is_querystring)
             explode_parameter(
-              name,
+              is_querystring ? nil : name,
               schema,
               version,
               definitions,
+              location: is_querystring ? 'query' : self.in,
               required: required?,
               deprecated: deprecated?
             )
           else
-            [
-              openapi_parameter(
-                name,
-                schema,
-                version,
-                description: description,
-                required: required?,
-                deprecated: deprecated?,
-                allow_empty_value: allow_empty_value?,
-                examples: examples
-              )
-            ]
-          end
+            [to_openapi(version, definitions)]
+          end.compact
         end
 
         private
 
-        def explode_parameter(name, schema, version, definitions, required:, deprecated:)
+        def explode_parameter(name, schema, version, definitions, location:, required:, deprecated:)
           schema.resolve_properties(definitions, context: :request).values.flat_map do |property|
             property_schema = property.schema.resolve(definitions)
-            parameter_name = "#{name}[#{property.name}]"
+            parameter_name = name ? "#{name}[#{property.name}]" : property.name
             required = (required && property.required?).presence
             deprecated = (deprecated || property_schema.deprecated?).presence
 
@@ -134,62 +140,79 @@ module Jsapi
                 property_schema,
                 version,
                 definitions,
+                location: location,
                 required: required,
                 deprecated: deprecated
               )
             else
               [
-                openapi_parameter(
+                openapi_parameter_object(
                   parameter_name,
                   property_schema,
                   version,
+                  location: location,
                   description: property_schema.description,
                   required: required,
                   deprecated: deprecated,
                   allow_empty_value: property.schema.existence <= Existence::ALLOW_EMPTY
                 )
               ]
-            end
+            end.compact
           end
         end
 
-        def openapi_parameter(name, schema, version,
-                              allow_empty_value:,
-                              deprecated:,
-                              description:,
-                              required:,
-                              examples: nil)
+        def openapi_parameter_object(name, schema, version,
+                                     allow_empty_value:,
+                                     deprecated:,
+                                     description:,
+                                     location:,
+                                     required:,
+                                     content_type: nil,
+                                     examples: nil)
 
-          name = schema.array? ? "#{name}[]" : name
+          return if location == 'querystring' && version < OpenAPI::V3_2
+
+          if schema.object? && version == OpenAPI::V2_0
+            raise "OpenAPI 2.0 doesn't allow object parameters in #{location}"
+          end
+
+          name = "#{name}[]" if schema.array?
 
           with_openapi_extensions(
-            if version.major == 2
-              raise "OpenAPI 2.0 doesn't allow object parameters " \
-                    "in #{self.in}" if schema.object?
-
-              {
-                name: name,
-                in: self.in,
-                description: description,
-                required: required.presence,
-                allowEmptyValue: allow_empty_value.presence,
-                collectionFormat: ('multi' if schema.array?)
-              }.merge(schema.to_openapi(version))
-            else
-              {
-                name: name,
-                in: self.in,
-                description: description,
-                required: required.presence,
-                allowEmptyValue: allow_empty_value.presence,
-                deprecated: deprecated.presence,
-                schema: schema.to_openapi(version).except(:deprecated),
-                examples: examples&.transform_values(&:to_openapi).presence
-
-                # NOTE: collectionFormat is replaced by 'style' and 'explode'.
-                #       The default values are equal to 'multi'.
-              }
-            end
+            name: name,
+            in: location,
+            description: description,
+            required: required.presence,
+            allowEmptyValue: allow_empty_value.presence,
+            **if version == OpenAPI::V2_0
+                {
+                  collectionFormat: ('multi' if schema.array?),
+                  **schema.to_openapi(version)
+                }
+              else
+                openapi_schema = schema.to_openapi(version).except(:deprecated)
+                openapi_examples = examples&.transform_values(&:to_openapi).presence
+                {
+                  deprecated: deprecated.presence,
+                  **if content_type.blank?
+                      # simple scenario
+                      {
+                        schema: openapi_schema,
+                        examples: openapi_examples
+                      }
+                    else
+                      # complex scenario
+                      {
+                        content: {
+                          content_type => {
+                            schema: openapi_schema,
+                            examples: openapi_examples
+                          }.compact
+                        }
+                      }
+                    end
+                }
+              end
           )
         end
       end

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

@@ -52,8 +52,9 @@ module Jsapi
               name: 'body',
               in: 'body',
               description: description,
-              required: required?
-            }.merge(schema.to_openapi(OpenAPI::V2_0))
+              required: required?,
+              **schema.to_openapi(OpenAPI::V2_0)
+            }
           )
         end
 

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

@@ -8,12 +8,13 @@ module Jsapi
         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.
+        # The content type, <code>"application/json"</code> by default.
         attribute :content_type, String, default: 'application/json'
 
         ##
@@ -46,12 +47,17 @@ module Jsapi
         # The Schema of the response.
         attribute :schema, accessors: %i[reader]
 
+        ##
+        # :attr: summary
+        # The short description of the response. Applies to \OpenAPI 3.2 and higher.
+        attribute :summary, String
+
         def initialize(keywords = {})
           keywords = keywords.dup
           super(
             keywords.extract!(
               :content_type, :description, :examples, :headers,
-              :links, :locale, :openapi_extensions
+              :links, :locale, :openapi_extensions, :summary
             )
           )
           add_example(value: keywords.delete(:example)) if keywords.key?(:example)
@@ -66,12 +72,17 @@ module Jsapi
           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)
 
           with_openapi_extensions(
-            if version.major == 2
+            if version == OpenAPI::V2_0
               {
                 description: description,
                 schema: schema.to_openapi(version),
@@ -86,17 +97,24 @@ module Jsapi
               }
             else
               {
+                summary: (summary if version >= OpenAPI::V3_2),
                 description: description,
+                headers: headers.transform_values do |header|
+                  header.to_openapi(version)
+                end.presence,
                 content: {
                   content_type => {
-                    schema: schema.to_openapi(version),
+                    **if json_seq_type? && schema.array? && version >= OpenAPI::V3_2
+                        { itemSchema: schema.items.to_openapi(version) }
+                      else
+                        { schema: schema.to_openapi(version) }
+                      end,
                     examples: examples.transform_values(&:to_openapi).presence
                   }.compact
                 },
-                headers: headers.transform_values do |header|
-                  header.to_openapi(version)
-                end.presence,
-                links: links.transform_values(&:to_openapi).presence
+                links: links.transform_values do |link|
+                  link.to_openapi(version)
+                end.presence
               }
             end
           )

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

@@ -121,7 +121,7 @@ module Jsapi
                 deprecated: deprecated?.presence
               }
             else
-              # OpenAPI 3.1
+              # OpenAPI 3.1 and higher
               {
                 type: nullable? ? [type, 'null'] : type,
                 examples: examples.presence,

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

@@ -4,8 +4,16 @@ module Jsapi
   module Meta
     module Schema
       class Discriminator < Model::Base
+        include OpenAPI::Extensions
+
+        ##
+        # :attr: default_mapping
+        # Applies to \OpenAPI 3.2 and higher.
+        attribute :default_mapping, String
+
         ##
         # :attr: mappings
+        # Applies to \OpenAPI 3.0 and higher.
         attribute :mappings, { Object => String }
 
         ##
@@ -15,12 +23,14 @@ module Jsapi
         # Returns a hash representing the \OpenAPI discriminator object.
         def to_openapi(version, *)
           version = OpenAPI::Version.from(version)
-          return property_name if version.major == 2
+          return property_name if version < OpenAPI::V3_0
 
-          {
+          result = {
             propertyName: property_name,
-            mapping: mappings.transform_keys(&:to_s).presence
-          }.compact
+            mapping: mappings.transform_keys(&:to_s).presence,
+            defaultMapping: (default_mapping if version >= OpenAPI::V3_2)
+          }
+          version >= OpenAPI::V3_1 ? with_openapi_extensions(result) : result.compact
         end
       end
     end

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

@@ -57,17 +57,36 @@ module Jsapi
 
           properties = resolve_properties(definitions, context: context)
 
-          property = properties[discriminator.property_name]
-          raise InvalidValueError.new('discriminator property',
-                                      discriminator.property_name,
-                                      valid_values: properties.keys) if property.nil?
+          discriminating_property = properties[discriminator.property_name]
+          if discriminating_property.nil?
+            raise InvalidValueError.new('discriminator property',
+                                        discriminator.property_name,
+                                        valid_values: properties.keys)
+          end
+
+          discriminating_value = discriminating_property.reader.call(object)
+          if discriminating_value.nil?
+            discriminating_value = discriminating_property.default_value(
+              definitions,
+              context: context
+            )
+            if discriminating_value.nil? && discriminator.default_mapping.nil?
+              raise "discriminating value can't be nil"
+            end
+          end
 
-          value = property.reader.call(object)
-          value = property.default_value(definitions, context: context) if value.nil?
-          raise "#{discriminator.property_name} can't be nil" if value.nil?
+          schema_name = discriminator.mapping(discriminating_value) || discriminating_value
 
-          schema = definitions.find_schema(discriminator.mapping(value) || value)
-          raise "inheriting schema couldn't be found: #{value.inspect}" if schema.nil?
+          schema = definitions.find_schema(schema_name)
+          if schema.nil?
+            default_mapping = discriminator.default_mapping
+            schema = definitions.find_schema(default_mapping) unless default_mapping.nil?
+
+            if schema.nil?
+              raise "inheriting schema couldn't be found: " \
+                    "#{[schema_name, default_mapping].compact.map(&:inspect).join(' or ')}"
+            end
+          end
 
           schema.resolve(definitions).resolve_schema(object, definitions, context: context)
         end

data/lib/jsapi/meta/schema/validation/maximum.rb

@@ -43,7 +43,7 @@ module Jsapi
 
           def to_openapi_validation(version)
             version = OpenAPI::Version.from(version)
-            return to_json_schema_validation if version.major == 3 && version.minor == 1
+            return to_json_schema_validation if version >= OpenAPI::V3_1
             return super unless exclusive
 
             { maximum: value, exclusiveMaximum: true }

data/lib/jsapi/meta/schema/validation/minimum.rb

@@ -43,7 +43,7 @@ module Jsapi
 
           def to_openapi_validation(version)
             version = OpenAPI::Version.from(version)
-            return to_json_schema_validation if version.major == 3 && version.minor == 1
+            return to_json_schema_validation if version >= OpenAPI::V3_1
             return super unless exclusive
 
             { minimum: value, exclusiveMinimum: true }

data/lib/jsapi/meta/security_scheme/api_key.rb

@@ -24,12 +24,11 @@ module Jsapi
         attribute :name, String
 
         # Returns a hash representing the \OpenAPI security scheme object.
-        def to_openapi(*)
+        def to_openapi(version, *)
+          version = OpenAPI::Version.from(version)
+
           with_openapi_extensions(
-            type: 'apiKey',
-            name: name,
-            in: self.in,
-            description: description
+            base_openapi_fields('apiKey', version).merge(name: name, in: self.in)
           )
         end
       end

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

@@ -8,6 +8,22 @@ module Jsapi
         # :attr: description
         # The description of the security scheme.
         attribute :description, String
+
+        ##
+        # :attr: deprecated
+        # Specifies whether or not the security scheme is deprecated.
+        # Applies to \OpenAPI 3.2 and higher.
+        attribute :deprecated, values: [true, false]
+
+        private
+
+        def base_openapi_fields(type, version)
+          {
+            type: type,
+            description: description,
+            deprecated: (deprecated?.presence if version >= OpenAPI::V3_2)
+          }
+        end
       end
     end
   end

data/lib/jsapi/meta/security_scheme/http/basic.rb

@@ -13,17 +13,10 @@ module Jsapi
             version = OpenAPI::Version.from(version)
 
             with_openapi_extensions(
-              if version.major == 2
-                {
-                  type: 'basic',
-                  description: description
-                }
+              if version < OpenAPI::V3_0
+                base_openapi_fields('basic', version)
               else
-                {
-                  type: 'http',
-                  scheme: 'basic',
-                  description: description
-                }
+                base_openapi_fields('http', version).merge(scheme: 'basic')
               end
             )
           end

data/lib/jsapi/meta/security_scheme/http/bearer.rb

@@ -7,7 +7,7 @@ module Jsapi
         # Specifies a security scheme based on bearer authentication.
         #
         # Note that Bearer authentication was introduced with \OpenAPI 3.0. Thus, a security
-        # scheme of this class is skipped when generating an \OpenAPI 2.0 document.
+        # scheme of this class is omitted when generating an \OpenAPI 2.0 document.
         class Bearer < Base
           include OpenAPI::Extensions
 
@@ -16,17 +16,17 @@ module Jsapi
           # The format of the bearer token.
           attribute :bearer_format, String
 
-          # Returns a hash representing the \OpenAPI security scheme object, or
-          # +nil+ if <code>version.major</code> is 2.
+          # Returns a hash representing the \OpenAPI security scheme object, or +nil+
+          # if <code>version</code> is less than \OpenAPI 3.0.
           def to_openapi(version, *)
             version = OpenAPI::Version.from(version)
-            return if version.major == 2
+            return if version < OpenAPI::V3_0
 
             with_openapi_extensions(
-              type: 'http',
-              scheme: 'bearer',
-              bearerFormat: bearer_format,
-              description: description
+              base_openapi_fields('http', version).merge(
+                scheme: 'bearer',
+                bearerFormat: bearer_format
+              )
             )
           end
         end

data/lib/jsapi/meta/security_scheme/http/other.rb

@@ -18,15 +18,13 @@ module Jsapi
           attribute :scheme, String
 
           # Returns a hash representing the \OpenAPI security scheme object, or +nil+
-          # if <code>version.major</code> is 2.
+          # if <code>version</code> is less than \OpenAPI 3.0.
           def to_openapi(version, *)
             version = OpenAPI::Version.from(version)
-            return if version.major == 2
+            return if version < OpenAPI::V3_0
 
             with_openapi_extensions(
-              type: 'http',
-              scheme: scheme,
-              description: description
+              base_openapi_fields('http', version).merge(scheme: scheme)
             )
           end
         end

data/lib/jsapi/meta/security_scheme/mutual_tls.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module SecurityScheme
+      # Specifies a security scheme based on MutualTLS.
+      class MutualTLS < Base
+        include OpenAPI::Extensions
+
+        # Returns a hash representing the \OpenAPI security scheme object, or +nil+
+        # if <code>version</code> is less than \OpenAPI 3.1.
+        def to_openapi(version, *)
+          version = OpenAPI::Version.from(version)
+          return if version < OpenAPI::V3_1
+
+          with_openapi_extensions(
+            base_openapi_fields('mutualTLS', version)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/security_scheme/oauth2.rb

@@ -9,34 +9,50 @@ module Jsapi
 
         ##
         # :attr: oauth_flows
-        # The hash containing the OAuth flows. Possible keys are:
+        # Maps one or more of the following keys to OAuthFlow objects.
         #
         # - <code>"authorization_code"</code>
         # - <code>"client_credentials"</code>
+        # - <code>"device_authorization"</code>
         # - <code>"implicit"</code>
         # - <code>"password"</code>
         #
-        # Values are OAuthFlow objects.
+        # Note that <code>"device_authorization"</code> was introduced with \OpenAPI 3.2.
+        # This entry is omitted when generating an \OpenAPI document with a lower version.
         attribute :oauth_flows, { String => OAuthFlow },
-                  keys: %w[authorization_code client_credentials implicit password]
+                  keys: %w[authorization_code
+                           client_credentials
+                           device_authorization
+                           implicit
+                           password]
+        ##
+        # :attr: oauth2_metadata_url
+        # The URL of the OAuth2 authorization server metadata.
+        # Applies to \OpenAPI 3.2 and higher.
+        attribute :oauth2_metadata_url, String
 
         # Returns a hash representing the \OpenAPI security scheme object.
         def to_openapi(version, *)
           version = OpenAPI::Version.from(version)
 
-          with_openapi_extensions(type: 'oauth2', description: description).tap do |h|
-            if oauth_flows.any?
-              if version.major == 2
-                key, oauth_flow = oauth_flows.first
-                h[:flow] = key.to_s
-                h.merge!(oauth_flow.to_openapi(version))
-              else
-                h[:flows] = oauth_flows.to_h do |key, value|
+          with_openapi_extensions(
+            base_openapi_fields('oauth2', version).tap do |fields|
+              flows = oauth_flows
+              flows = flows.except('device_authorization') unless version >= OpenAPI::V3_2
+
+              if version >= OpenAPI::V3_0
+                fields[:flows] = flows.to_h do |key, value|
                   [key.to_s.camelize(:lower).to_sym, value.to_openapi(version)]
-                end
+                end if flows.any?
+
+                fields[:oauth2MetadataUrl] = oauth2_metadata_url if version >= OpenAPI::V3_2
+              elsif flows.one?
+                key, flow = flows.first
+                fields[:flow] = key.to_s
+                fields.merge!(flow.to_openapi(version))
               end
             end
-          end
+          )
         end
       end
     end

data/lib/jsapi/meta/security_scheme/open_id_connect.rb

@@ -4,9 +4,6 @@ module Jsapi
   module Meta
     module SecurityScheme
       # Specifies a security scheme based on OpenID Connect.
-      #
-      # OpenID Connect was introduced with \OpenAPI 3.0. Thus, a security scheme of
-      # this class is skipped when generating an \OpenAPI 2.0 document.
       class OpenIDConnect < Base
         include OpenAPI::Extensions
 
@@ -15,15 +12,15 @@ module Jsapi
         attribute :open_id_connect_url, String
 
         # Returns a hash representing the \OpenAPI security scheme object, or +nil+
-        # if <code>version.major</code> is 2.
+        # if <code>version</code> is less than \OpenAPI 3.0.
         def to_openapi(version, *)
           version = OpenAPI::Version.from(version)
-          return if version.major == 2
+          return if version < OpenAPI::V3_0
 
           with_openapi_extensions(
-            type: 'openIdConnect',
-            openIdConnectUrl: open_id_connect_url,
-            description: description
+            base_openapi_fields('openIdConnect', version).merge(
+              openIdConnectUrl: open_id_connect_url
+            )
           )
         end
       end

data/lib/jsapi/meta/security_scheme.rb

@@ -3,6 +3,7 @@
 require_relative 'security_scheme/base'
 require_relative 'security_scheme/api_key'
 require_relative 'security_scheme/http'
+require_relative 'security_scheme/mutual_tls'
 require_relative 'security_scheme/oauth2'
 require_relative 'security_scheme/open_id_connect'
 
@@ -31,6 +32,8 @@ module Jsapi
             HTTP.new(keywords.merge(scheme: 'basic'))
           when 'http' # OpenAPI 3.0 and higher
             HTTP.new(keywords)
+          when 'mutual_tls' # OpenAPI 3.1 and higher
+            MutualTLS.new(keywords)
           when 'oauth2'
             OAuth2.new(keywords)
           when 'open_id_connect' # OpenAPI 3.0 and higher

data/lib/jsapi/meta/server.rb

@@ -11,6 +11,11 @@ module Jsapi
       # The description of the server.
       attribute :description, String
 
+      ##
+      # :attr: name
+      # The optional unique name of the server. Applies to \OpenAPI 3.2 and higher.
+      attribute :name, String
+
       ##
       # :attr: url
       # The absolute or relative URL of the server.
@@ -22,10 +27,13 @@ module Jsapi
       attribute :variables, { String => ServerVariable }
 
       # Returns a hash representing the \OpenAPI server object.
-      def to_openapi(*)
+      def to_openapi(version, *)
+        version = OpenAPI::Version.from(version)
+
         with_openapi_extensions(
           url: url,
           description: description,
+          name: (name if version >= OpenAPI::V3_2),
           variables: variables.transform_values(&:to_openapi).presence
         )
       end

data/lib/jsapi/meta/tag.rb

@@ -16,17 +16,47 @@ module Jsapi
       # The ExternalDocumentation object.
       attribute :external_docs, ExternalDocumentation
 
+      ##
+      # :attr: kind
+      # The category of the tag. Applies to \OpenAPI 3.2 and higher.
+      attribute :kind, String
+
       ##
       # :attr: name
       # The name of the tag.
       attribute :name, String
 
+      ##
+      # :attr: parent
+      # The name of the parent tag. Applies to \OpenAPI 3.2 and higher.
+      attribute :parent, String
+
+      ##
+      # :attr: summary
+      # The short summary of the tag. Applies to \OpenAPI 3.2 and higher.
+      attribute :summary, String
+
       # Returns a hash representing the \OpenAPI tag object.
-      def to_openapi(*)
+      def to_openapi(version, *)
+        version = OpenAPI::Version.from(version)
+
         with_openapi_extensions(
-          name: name,
-          description: description,
-          externalDocs: external_docs&.to_openapi
+          if version >= OpenAPI::V3_2
+            {
+              name: name,
+              summary: summary,
+              description: description,
+              externalDocs: external_docs&.to_openapi,
+              parent: parent,
+              kind: kind
+            }
+          else
+            {
+              name: name,
+              description: description,
+              externalDocs: external_docs&.to_openapi
+            }
+          end
         )
       end
     end

data/lib/jsapi/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsapi
 version: !ruby/object:Gem::Version
-  version: '1.2'
+  version: '1.3'
 platform: ruby
 authors:
 - Denis Göller
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-30 00:00:00.000000000 Z
+date: 2025-11-02 00:00:00.000000000 Z
 dependencies: []
 description:
 email: denis@dmgoeller.de
@@ -80,6 +80,7 @@ files:
 - lib/jsapi/meta/oauth_flow.rb
 - lib/jsapi/meta/openapi.rb
 - lib/jsapi/meta/openapi/extensions.rb
+- lib/jsapi/meta/openapi/path_item.rb
 - lib/jsapi/meta/openapi/version.rb
 - lib/jsapi/meta/operation.rb
 - lib/jsapi/meta/parameter.rb
@@ -128,6 +129,7 @@ files:
 - lib/jsapi/meta/security_scheme/http/basic.rb
 - lib/jsapi/meta/security_scheme/http/bearer.rb
 - lib/jsapi/meta/security_scheme/http/other.rb
+- lib/jsapi/meta/security_scheme/mutual_tls.rb
 - lib/jsapi/meta/security_scheme/oauth2.rb
 - lib/jsapi/meta/security_scheme/open_id_connect.rb
 - lib/jsapi/meta/server.rb