jsapi 1.4 → 2.0

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

@@ -7,70 +7,107 @@ module Jsapi
       class Base < Model::Base
         include OpenAPI::Extensions
 
-        delegate_missing_to :schema
+        # To still allow to specify content-related directives within blocks
+        delegate_missing_to :last_content
 
         ##
-        # :attr: content_type
-        # The content type. <code>"application/json"</code> by default.
-        attribute :content_type, String, default: 'application/json'
+        # :attr_reader: contents
+        # The alternative contents of the request body. Maps instances of
+        # Media::Range to Content objects.
+        attribute :contents, { Media::Range => Content }, accessors: %i[reader writer]
 
         ##
         # :attr: description
         # The description of the request body.
         attribute :description, String
 
-        ##
-        # :attr_reader: examples
-        # The Example objects.
-        attribute :examples, { String => Example }, default_key: 'default'
-
-        ##
-        # :attr_reader: schema
-        # The Schema of the request body.
-        attribute :schema, accessors: %i[reader]
-
         def initialize(keywords = {})
           keywords = keywords.dup
-          super(keywords.extract!(:content_type, :description, :examples, :openapi_extensions))
+          content_keywords = keywords.slice!(*self.class.attribute_names)
+
+          # Move content-related keywords to :contents so that the first
+          # key-value pair in @contents is created from them.
+          if content_keywords.present?
+            content_type = content_keywords.delete(:content_type)
 
-          add_example(value: keywords.delete(:example)) if keywords.key?(:example)
-          keywords[:ref] = keywords.delete(:schema) if keywords.key?(:schema)
+            (keywords[:contents] ||= {}).reverse_merge!(
+              { content_type => content_keywords }
+            )
+          end
+          super(keywords)
+        end
 
-          @schema = Schema.new(keywords)
+        def attribute_changed(name) # :nodoc:
+          @default_media_range = @default_content = @sorted_contents = nil if name == :contents
+          super
         end
 
-        # Returns true if the level of existence is greater than or equal to
-        # +ALLOW_NIL+, false otherwise.
-        def required?
-          schema.existence >= Existence::ALLOW_NIL
+        def add_content(media_range = nil, keywords = {}) # :nodoc:
+          try_modify_attribute!(:contents) do
+            media_range, keywords = nil, media_range if media_range.is_a?(Hash)
+            media_range = Media::Range.from(media_range || Media::Range::APPLICATION_JSON)
+
+            (@contents ||= {})[media_range] = Content.new(keywords)
+          end
         end
 
-        # Returns a hash representing the \OpenAPI 2.0 parameter object.
+        # Returns the most appropriate content for the given media type.
+        def content_for(media_type)
+          (@sorted_contents ||= contents.sort)
+            .find { |media_range, _content| media_range =~ media_type }
+            &.second || default_content
+        end
+
+        def default_content
+          @default_content ||= contents.values.first
+        end
+
+        def default_media_range
+          @default_media_range = contents.keys.first
+        end
+
+        def freeze_attributes # :nodoc:
+          add_content if contents.blank?
+          super
+        end
+
+        # Returns a hash representing the \OpenAPI parameter object.
+        #
+        # Applies to \OpenAPI 2.0.
         def to_openapi_parameter
+          schema = default_content.schema
+
           with_openapi_extensions(
             {
               name: 'body',
               in: 'body',
               description: description,
-              required: required?,
+              required: schema.existence >= Existence::ALLOW_NIL,
               **schema.to_openapi(OpenAPI::V2_0)
             }
           )
         end
 
-        # Returns a hash representing the \OpenAPI 3.x request body object.
+        # Returns a hash representing the \OpenAPI request body object.
+        #
+        # Applies to \OpenAPI 3.0 and higher.
         def to_openapi(version, *)
           with_openapi_extensions(
             description: description,
-            content: {
-              content_type => {
-                schema: schema.to_openapi(version),
-                examples: examples.transform_values(&:to_openapi).presence
-              }.compact
-            },
-            required: required?
+            content: contents.transform_values do |content|
+              content.to_openapi(version)
+            end,
+            required: contents.values.all? do |content|
+              content.schema.existence >= Existence::ALLOW_NIL
+            end
           )
         end
+
+        private
+
+        def last_content
+          contents.values.last || add_content
+        end
       end
     end
   end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module RequestBody
+      class Wrapper < Model::Wrapper
+        def content_for(media_type)
+          Content.wrap(super, definitions)
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/request_body.rb

@@ -2,10 +2,13 @@
 
 require_relative 'request_body/base'
 require_relative 'request_body/reference'
+require_relative 'request_body/wrapper'
 
 module Jsapi
   module Meta
     module RequestBody
+      include Model::Wrappable
+
       class << self
         # Creates a Base or Reference.
         def new(keywords = {})

data/lib/jsapi/meta/rescue_handler.rb

@@ -2,31 +2,32 @@
 
 module Jsapi
   module Meta
-    # Maps an error class to a response status.
+    # Specifies a rescue handler.
     class RescueHandler < Model::Base
       ##
       # :attr: error_class
-      # The error class to be mapped.
-      attribute :error_class, default: StandardError
+      # The error class to be rescued.
+      attribute :error_class, default: StandardError, accessors: %i[reader]
 
       ##
-      # :attr: status
-      # The response status. The default is <code>"default"</code>.
-      attribute :status, default: 'default'
+      # :attr: status_code
+      # The Status::Code replacing the original status code when rescuing an
+      # instance of error_class.
+      attribute :status_code, Status::Code
 
-      def initialize(keywords = {})
-        super
-        unless error_class.is_a?(Class)
-          raise ArgumentError, "#{error_class.inspect} isn't a class"
-        end
-        unless error_class <= StandardError
-          raise ArgumentError, "#{error_class.inspect} isn't a rescuable class"
-        end
+      def error_class=(klass) # :nodoc:
+        raise ArgumentError, "#{klass.inspect} isn't a class" \
+        unless klass.is_a?(Class)
+
+        raise ArgumentError, "#{klass.inspect} isn't a rescuable class" \
+        unless klass <= StandardError
+
+        @error_class = klass
       end
 
-      # Returns true if +exception+ is an instance of the class to be mapped, false otherwise.
-      def match?(exception)
-        exception.is_a?(error_class)
+      # Returns true if +error+ is an instance of error_class.
+      def match?(error)
+        error.is_a?(error_class)
       end
     end
   end

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

@@ -7,74 +7,94 @@ 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
+        # To still allow to specify content-related directives within blocks
+        delegate_missing_to :last_content
 
         ##
-        # :attr: content_type
-        # The content type, <code>"application/json"</code> by default.
-        attribute :content_type, String, default: 'application/json'
+        # :attr_reader: contents
+        # The alternative contents of the response. Maps instances of
+        # Media::Range to Content objects.
+        attribute :contents, { Media::Type => Content }, accessors: %i[reader writer]
 
         ##
         # :attr: description
         # The description of the response.
         attribute :description, String
 
-        ##
-        # :attr: examples
-        # The Example objects.
-        attribute :examples, { String => Example }, default_key: 'default'
-
         ##
         # :attr: headers
-        # The Header objects.
+        # The headers of the response. Maps header names to Header objects or
+        # references.
         attribute :headers, { String => Header }
 
         ##
         # :attr: links
-        # The Link objects.
+        # The linked operations. Maps link names to Link objects.
         attribute :links, { String => Link }
 
         ##
         # :attr: locale
-        # The locale used when rendering a response.
+        # The locale to be used instead of the default locale when rendering
+        # a response.
         attribute :locale, Symbol
 
         ##
-        # :attr_reader: schema
-        # The Schema of the response.
-        attribute :schema, accessors: %i[reader]
+        # :attr: nodoc
+        # Prevents the response to be described in generated \OpenAPI documents.
+        attribute :nodoc, values: [true, false], default: false
 
         ##
         # :attr: summary
-        # The short description of the response. Applies to \OpenAPI 3.2 and higher.
+        # 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, :summary
+          content_keywords = keywords.slice!(*self.class.attribute_names)
+
+          # Move content-related keywords to :contents so that the first
+          # key-value pair in @contents is created from them.
+          if content_keywords.present?
+            content_type = content_keywords.delete(:content_type)
+
+            (keywords[:contents] ||= {}).reverse_merge!(
+              { content_type => content_keywords }
             )
-          )
-          add_example(value: keywords.delete(:example)) if keywords.key?(:example)
-          keywords[:ref] = keywords.delete(:schema) if keywords.key?(:schema)
+          end
+          super(keywords)
+        end
 
-          @schema = Schema.new(keywords)
+        def attribute_changed(name) # :nodoc:
+          @default_media_type = nil if name == :contents
+          super
         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)
+        def add_content(media_type = nil, keywords = {}) # :nodoc:
+          try_modify_attribute!(:contents) do
+            media_type, keywords = nil, media_type if media_type.is_a?(Hash)
+            media_type = Media::Type.from(media_type || Media::Type::APPLICATION_JSON)
+
+            (@contents ||= {})[media_type] = Content.new(keywords)
+          end
+        end
+
+        def default_media_type
+          @default_media_type ||= contents.keys.first
         end
 
-        # Returns true if content type is <code>"application/json-seq"</code>.
-        def json_seq_type?
-          content_type == JSON_SEQ_TYPE
+        # Returns the most appropriate media type and content for the given
+        # media ranges.
+        def media_type_and_content_for(*media_ranges)
+          media_ranges
+            .filter_map { |media_range| Media::Range.try_from(media_range) }
+            .sort # e.g. "text/plain" before "text/*" before "*/*"
+            .lazy.map do |media_range|
+              contents.find do |media_type_and_content|
+                media_range =~ media_type_and_content.first
+              end
+            end.first || contents.first
         end
 
         # Returns a hash representing the \OpenAPI response object.
@@ -83,42 +103,46 @@ module Jsapi
 
           with_openapi_extensions(
             if version == OpenAPI::V2_0
+              media_type, content = contents.first
+              example = content&.examples&.values&.first
               {
                 description: description,
-                schema: schema.to_openapi(version),
-                headers: headers.transform_values do |header|
-                  header.to_openapi(version) unless header.reference?
-                end.compact.presence,
-                examples: (
-                  if (example = examples.values.first).present?
-                    { content_type => example.resolve(definitions).value }
+                schema: content&.schema&.to_openapi(version),
+                headers:
+                  headers.transform_values do |header|
+                    header.to_openapi(version) unless header.reference?
+                  end.compact.presence,
+                examples:
+                  if media_type.present? && example.present?
+                    { media_type => example.resolve(definitions).value }
                   end
-                )
               }
             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 => {
-                    **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
-                },
-                links: links.transform_values do |link|
-                  link.to_openapi(version)
-                end.presence
+                headers:
+                  headers.transform_values do |header|
+                    header.to_openapi(version)
+                  end.presence,
+                content:
+                  contents.to_h do |nth_media_type, nth_content|
+                    [nth_media_type, nth_content.to_openapi(version, nth_media_type)]
+                  end.presence,
+                links:
+                  links.transform_values do |link|
+                    link.to_openapi(version)
+                  end.presence
               }
             end
           )
         end
+
+        private
+
+        def last_content
+          contents.values.last || (add_content unless attributes_frozen?)
+        end
       end
     end
   end

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

@@ -4,7 +4,17 @@ module Jsapi
   module Meta
     module Response
       # Refers a reusable response.
-      class Reference < Model::Reference; end
+      class Reference < Model::Reference
+        ##
+        # :attr: locale
+        # Overrides the locale of the referred response.
+        attribute :locale, Symbol
+
+        ##
+        # :attr: nodoc
+        # Prevents the reference to be described in generated \OpenAPI documents.
+        attribute :nodoc, values: [true, false]
+      end
     end
   end
 end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Response
+      class Wrapper < Model::Wrapper
+        # The locale of the wrapped response or reference.
+        attr_reader :locale
+
+        def initialize(response, definitions)
+          @locale = response.resolve_lazily(definitions).locale
+          super
+        end
+
+        def media_type_and_content_for(*media_ranges)
+          super&.then do |media_type_and_content|
+            [
+              media_type_and_content.first,
+              Content.wrap(media_type_and_content.second, definitions)
+            ]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/response.rb

@@ -2,10 +2,13 @@
 
 require_relative 'response/base'
 require_relative 'response/reference'
+require_relative 'response/wrapper'
 
 module Jsapi
   module Meta
     module Response
+      include Model::Wrappable
+
       class << self
         # Creates a Base or Reference.
         def new(keywords = {})

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

@@ -4,6 +4,8 @@ module Jsapi
   module Meta
     module Schema
       class AdditionalProperties < Model::Base
+        include Model::Wrappable
+
         delegate_missing_to :schema
 
         ##
@@ -24,6 +26,12 @@ module Jsapi
 
           @schema = Schema.new(keywords)
         end
+
+        class Wrapper < Model::Wrapper
+          def schema
+            @schema ||= Schema.wrap(super, definitions)
+          end
+        end
       end
     end
   end

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

@@ -4,6 +4,12 @@ module Jsapi
   module Meta
     module Schema
       class Array < Base
+        class Wrapper < Schema::Wrapper
+          def items
+            @items ||= Schema.wrap(super, definitions)
+          end
+        end
+
         ##
         # :attr: items
         # The Schema defining the kind of items.
@@ -20,21 +26,27 @@ module Jsapi
         attribute :min_items, accessors: %i[reader]
 
         def items=(keywords = {}) # :nodoc:
-          if keywords.key?(:schema)
-            keywords = keywords.dup
-            keywords[:ref] = keywords.delete(:schema)
+          try_modify_attribute!(:items) do
+            if keywords.key?(:schema)
+              keywords = keywords.dup
+              keywords[:ref] = keywords.delete(:schema)
+            end
+            @items = Schema.new(keywords)
           end
-          @items = Schema.new(keywords)
         end
 
         def max_items=(value) # :nodoc:
-          add_validation('max_items', Validation::MaxItems.new(value))
-          @max_items = value
+          try_modify_attribute!(:max_items) do
+            add_validation('max_items', Validation::MaxItems.new(value))
+            @max_items = value
+          end
         end
 
         def min_items=(value) # :nodoc:
-          add_validation('min_items', Validation::MinItems.new(value))
-          @min_items = value
+          try_modify_attribute!(:min_items) do
+            add_validation('min_items', Validation::MinItems.new(value))
+            @min_items = value
+          end
         end
 
         def to_json_schema # :nodoc:

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

@@ -3,6 +3,8 @@
 module Jsapi
   module Meta
     module Schema
+      TYPES = %w[array boolean integer number object string].freeze # :nodoc:
+
       class Base < Model::Base
         include OpenAPI::Extensions
 
@@ -13,7 +15,7 @@ module Jsapi
 
         ##
         # :attr: deprecated
-        # Specifies whether or not the schema is deprecated.
+        # Specifies whether the schema is marked as deprecated.
         attribute :deprecated, values: [true, false]
 
         ##
@@ -33,7 +35,7 @@ module Jsapi
 
         ##
         # :attr: external_docs
-        # The OpenAPI::ExternalDocumentation object.
+        # The ExternalDocumentation object.
         attribute :external_docs, ExternalDocumentation
 
         ##
@@ -63,16 +65,15 @@ module Jsapi
           super(keywords)
         end
 
-        # Returns the default value within +context+.
-        def default_value(definitions = nil, context: nil)
-          return default unless default.nil?
-
-          definitions&.default_value(type, context: context)
+        TYPES.each do |type|
+          define_method(:"#{type}?") { self.type == type }
         end
 
         def enum=(value) # :nodoc:
-          add_validation('enum', Validation::Enum.new(value))
-          @enum = value
+          try_modify_attribute!(:enum) do
+            add_validation('enum', Validation::Enum.new(value))
+            @enum = value
+          end
         end
 
         # Returns true if and only if values can be +null+ as specified by \JSON \Schema.

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