jsapi 1.4 → 2.0

data/lib/jsapi/dsl/shared_operation_methods.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module DSL
+    module SharedOperationMethods
+      # Specifies the model class to access top-level parameters by.
+      #
+      #   model Foo do
+      #     def bar
+      #       # ...
+      #     end
+      #   end
+      #
+      # +klass+ can be any subclass of Model::Base. If block is given, an anonymous
+      # class is created that inherits either from +klass+ or Model::Base.
+      #
+      # See Meta::Operation#model and Meta::Path#model for further information.
+      def model(klass = nil, &block)
+        if block
+          klass = Class.new(klass || Model::Base)
+          klass.class_eval(&block)
+        end
+        @meta_model.model = klass
+      end
+
+      # Specifies a parameter.
+      #
+      #   parameter 'foo', type: 'string'
+      #
+      #   parameter 'foo', type: 'object' do
+      #     property 'bar', type: 'string'
+      #   end
+      #
+      # Refers a resuable parameter if the +:ref+ keyword is specified.
+      #
+      #   parameter ref: 'foo'
+      #
+      # Refers the reusable parameter with the same name if neither any
+      # keywords nor a block is specified.
+      #
+      #   parameter 'foo'
+      #
+      # See Meta::Operation#parameters and Meta::Path#parameters for further
+      # information.
+      def parameter(name = nil, **keywords, &block)
+        define('parameter', name&.inspect) do
+          name = keywords[:ref] if name.nil?
+          keywords = { ref: name } unless keywords.any? || block
+
+          @meta_model.add_parameter(name, keywords).tap do |parameter_model|
+            Parameter.new(parameter_model, &block) if block
+          end
+        end
+      end
+
+      ##
+      # :call-seq:
+      #   request_body(**keywords, &block)
+      #   request_body(name)
+      #
+      # Specifies a request body.
+      #
+      #   request_body type: 'object' do
+      #     property 'foo', type: 'string'
+      #   end
+      #
+      # Refers a resuable request body if the +:ref+ keyword is specified.
+      #
+      #   request_body ref: 'foo'
+      #
+      # Refers the reusable request body with the same name if neither any
+      # keywords nor a block is specified.
+      #
+      #   request_body 'foo'
+      #
+      # See Meta::Operation#request_body and Meta::Path#request_body for
+      # further information.
+      def request_body(name = nil, **keywords, &block)
+        define('request body') do
+          raise Error, "name can't be specified together with keywords or a block" \
+          if name && (keywords.any? || block)
+
+          keywords = { ref: name } if name
+          @meta_model.request_body = keywords
+
+          @meta_model.request_body.tap do |request_body|
+            RequestBody.new(request_body, &block) if block
+          end
+        end
+      end
+
+      ##
+      # :call-seq:
+      #   response(status = nil, **keywords, &block)
+      #   response(status, name)
+      #   response(name)
+      #
+      # Specifies a response.
+      #
+      #   response 200, type: 'object' do
+      #     property 'foo', type: 'string'
+      #   end
+      #
+      # The default status is <code>"default"</code>.
+      #
+      # Refers a resuable response if the +:ref+ keyword is specified.
+      #
+      #   response 200, ref: 'foo'
+      #
+      # Refers the reusable response with the same name if neither any
+      # keywords nor a block is specified.
+      #
+      #   response 'foo'
+      #
+      # See Meta::Operation#responses and Meta::Path#responses for further
+      # information.
+      def response(status = nil, name = nil, **keywords, &block)
+        define('response', status&.inspect) do
+          if keywords.none? && !block
+            status, name = nil, status unless name
+            keywords = { ref: name }
+          elsif name
+            raise Error, "name can't be specified together with keywords or a block"
+          end
+
+          @meta_model.add_response(status, keywords).tap do |response_model|
+            Response.new(response_model, &block) if block
+          end
+        end
+      end
+
+      ##
+      # :method: tag
+      # :args: name
+      # Specifies a tag.
+      #
+      #   tag 'foo'
+    end
+  end
+end

data/lib/jsapi/dsl.rb

@@ -1,13 +1,12 @@
 # frozen_string_literal: true
 
-require_relative 'dsl/error'
 require_relative 'dsl/base'
 require_relative 'dsl/examples'
 require_relative 'dsl/schema'
 require_relative 'dsl/parameter'
 require_relative 'dsl/request_body'
 require_relative 'dsl/response'
-require_relative 'dsl/callback'
+require_relative 'dsl/shared_operation_methods'
 require_relative 'dsl/operation'
 require_relative 'dsl/path'
 require_relative 'dsl/definitions'

data/lib/jsapi/json/array.rb

@@ -4,10 +4,10 @@ module Jsapi
   module JSON
     # Represents a JSON array.
     class Array < Value
-      def initialize(array, schema, definitions, context: nil)
+      def initialize(array, schema, context: nil)
         super(schema)
         @json_values = Array(array).map do |item|
-          JSON.wrap(item, schema.items, definitions, context: context)
+          JSON.wrap(item, schema.items, context: context)
         end
       end
 

data/lib/jsapi/json/object.rb

@@ -10,20 +10,20 @@ module Jsapi
 
       attr_reader :raw_additional_attributes, :raw_attributes
 
-      def initialize(hash, schema, definitions, context: nil)
-        schema = schema.resolve_schema(hash, definitions, context: context)
-        properties = schema.resolve_properties(definitions, context: context)
+      def initialize(hash, schema, context: nil)
+        schema = schema.resolve_schema(hash, context: context)
+        properties = schema.resolve_properties(context: context)
 
         @raw_attributes = properties.transform_values do |property|
-          JSON.wrap(hash[property.name], property.schema, definitions, context: context)
+          JSON.wrap(hash[property.name], property.schema, context: context)
         end
 
         @raw_additional_attributes =
           if (additional_properties = schema.additional_properties)
-            additional_properties_schema = additional_properties.schema.resolve(definitions)
+            additional_properties_schema = additional_properties.schema
 
             hash.except(*properties.keys).transform_values do |value|
-              JSON.wrap(value, additional_properties_schema, definitions, context: context)
+              JSON.wrap(value, additional_properties_schema, context: context)
             end
           end || {}
 

data/lib/jsapi/json.rb

@@ -13,15 +13,13 @@ module Jsapi
   # Provides a DOM for JSON values.
   module JSON
     class << self
-      def wrap(object, schema, definitions = nil, context: nil)
-        schema = schema.resolve(definitions) unless definitions.nil?
-
-        object = schema.default_value(definitions, context: context) if object.nil?
+      def wrap(object, schema, context: nil)
+        object = schema.default_value(context: context) if object.nil?
         return Null.new(schema) if object.nil?
 
         case schema.type
         when 'array'
-          Array.new(object, schema, definitions, context: context)
+          Array.new(object, schema, context: context)
         when 'boolean'
           Boolean.new(object, schema)
         when 'integer'
@@ -29,7 +27,7 @@ module Jsapi
         when 'number'
           Number.new(object, schema)
         when 'object'
-          Object.new(object, schema, definitions, context: context)
+          Object.new(object, schema, context: context)
         when 'string'
           String.new(object, schema)
         else

data/lib/jsapi/media/range.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative 'type_and_subtype'
+
+module Jsapi
+  module Media
+    # Represents a media range.
+    class Range
+      include Comparable
+      include TypeAndSubtype
+
+      # Range for all types (<code>"\*/\*"</code>).
+      ALL = Range.new('*', '*')
+
+      # Range for \JSON type (<code>"application/json"</code>).
+      APPLICATION_JSON = Range.new('application', 'json')
+
+      class << self
+        # Transforms +value+ to an instance of this class.
+        #
+        # Raises an +ArgumentError+ when +value+ could not be transformed.
+        def from(value)
+          media_range = try_from(value)
+          return media_range unless media_range.nil?
+
+          raise ArgumentError, "invalid media range: #{value.inspect}"
+        end
+
+        # Reduces the given collection of media ranges by removing media ranges
+        # that are already covered by another media range.
+        def reduce(media_ranges)
+          media_ranges.each_with_object([]) do |media_range, memo|
+            media_range = from(media_range)
+            if memo.none? { |other| other.cover?(media_range) }
+              memo.delete_if { |other| media_range.cover?(other) }
+              memo << media_range
+            end
+          end.sort
+        end
+
+        # Tries to transform +value+ to an instance of this class.
+        #
+        # Returns nil if +value+ could not be transformed.
+        def try_from(value)
+          return value if value.is_a?(Range)
+
+          type_and_subtype = pattern.match(value.to_s)&.captures
+          new(*type_and_subtype) if type_and_subtype&.count == 2
+        end
+
+        private
+
+        def pattern
+          @pattern ||= begin
+            name = '[0-9a-zA-Z-]+'
+            %r{(\*|#{name})/(\*|(?:#{name}(?:\.#{name})?(?:\+#{name})?))}.freeze
+          end
+        end
+      end
+
+      # Compares it with +other+ by +priority+.
+      def <=>(other)
+        return unless other.is_a?(self.class)
+
+        result = priority <=> other.priority
+        return result unless result.zero?
+
+        result = type <=> other.type
+        return result unless result.zero?
+
+        subtype <=> other.subtype
+      end
+
+      # Returns true if it covers +other+.
+      def cover?(other)
+        return if other.nil?
+
+        other = Range.from(other)
+
+        (type == '*' || type == other.type) &&
+          (subtype == '*' || subtype == other.subtype)
+      end
+
+      # Returns true if the given media type matches the media range.
+      def match?(media_type)
+        return if media_type.nil?
+
+        media_type = Type.from(media_type)
+
+        (type == '*' || type == media_type.type) &&
+          (subtype == '*' || subtype == media_type.subtype)
+      end
+
+      alias =~ match?
+
+      # Returns the level of priority of the media range.
+      def priority
+        @priority ||= (type == '*' ? 2 : 0) + (subtype == '*' ? 1 : 0) + 1
+      end
+    end
+  end
+end

data/lib/jsapi/media/type.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative 'type_and_subtype'
+
+module Jsapi
+  module Media
+    # Represents a media type.
+    class Type
+      include Comparable
+      include TypeAndSubtype
+
+      # Media::Type for <code>"application/json"</code>.
+      APPLICATION_JSON = Type.new('application', 'json')
+
+      # Media::Type for <code>"application/json-seq"</code>.
+      APPLICATION_JSON_SEQ = Type.new('application', 'json-seq')
+
+      # Media::Type for <code>"text/plain"</code>.
+      TEXT_PLAIN = Type.new('text', 'plain')
+
+      class << self
+        # Transforms +value+ to an instance of this class.
+        #
+        # Raises an ArgumentError when +value+ could not be transformed.
+        def from(value)
+          media_type = try_from(value)
+          return media_type unless media_type.nil?
+
+          raise ArgumentError, "invalid media type: #{value.inspect}"
+        end
+
+        # Tries to transform +value+ to an instance of this class.
+        #
+        # Returns nil if +value+ could not be transformed.
+        def try_from(value)
+          return value if value.is_a?(Type)
+
+          type_and_subtype = pattern.match(value.to_s)&.captures
+          new(*type_and_subtype) if type_and_subtype&.count == 2
+        end
+
+        private
+
+        def pattern
+          @pattern ||= begin
+            name = '[0-9a-zA-Z-]+'
+            %r{(#{name})/(#{name}(?:\.#{name})?(?:\+#{name})?)}.freeze
+          end
+        end
+      end
+
+      # Compares it with +other+ by +type+ and +subtype+.
+      def <=>(other)
+        return unless other.is_a?(self.class)
+
+        result = type <=> other.type
+        return result unless result.zero?
+
+        subtype <=> other.subtype
+      end
+
+      # Returns true if it represents a JSON media type as specified by
+      # https://mimesniff.spec.whatwg.org/#json-mime-type.
+      def json?
+        (type.in?(%w[application text]) && subtype == 'json') ||
+          subtype.end_with?('+json')
+      end
+    end
+  end
+end

data/lib/jsapi/media/type_and_subtype.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Media
+    module TypeAndSubtype # :nodoc:
+      def self.included(base)
+        base.attr_reader :type, :subtype
+      end
+
+      def initialize(type, subtype)
+        @type = type.downcase
+        @subtype = subtype.downcase
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          type == other.type &&
+          subtype == other.subtype
+      end
+
+      alias eql? ==
+
+      def hash
+        @hash ||= [type, subtype].hash
+      end
+
+      def inspect
+        "#<#{self.class} #{to_s.inspect}>"
+      end
+
+      def to_s
+        @to_s ||= "#{type}/#{subtype}"
+      end
+
+      alias as_json to_s
+    end
+  end
+end

data/lib/jsapi/media.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'media/range'
+require_relative 'media/type'
+
+module Jsapi
+  # Provides classes to deal with media types.
+  module Media end
+end

data/lib/jsapi/messages.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Messages # :nodoc:
+    class << self
+      def invalid_value(name:, value:, valid_values: [])
+        case valid_values.count
+        when 0
+          "#{name} must not be #{value.inspect}"
+        when 1
+          "#{name} must be #{valid_values.first.inspect}, is #{value.inspect}"
+        else
+          "#{name} must be one of #{valid_values[0..-2].map(&:inspect).join(', ')} " \
+          "or #{valid_values.last.inspect}, is #{value.inspect}"
+        end
+      end
+    end
+  end
+end

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

@@ -2,28 +2,83 @@
 
 module Jsapi
   module Meta
+    module Parameter; end
     class Operation < Model::Base; end
 
     module Callback
       # Specifies a callback. Applies to \OpenAPI 3.0 and higher.
       class Base < Model::Base
+        # The set of operations that can be called backed.
+        class Operations < Model::Base
+          ##
+          # :attr: description
+          # The description that applies to all operations.
+          attribute :description, String
+
+          ##
+          # :attr: operations
+          # The operations. Maps strings to Operation objects.
+          attribute :operations, { String => Operation }, accessors: %i[reader writer]
+
+          ##
+          # :attr: parameters
+          # The parameters that apply for all operations. Maps parameter names
+          # to Parameter objects or references.
+          attribute :parameters, { String => Parameter }, accessors: %i[reader writer]
+
+          ##
+          # :attr: summary
+          # The short summary that applies to all operations.
+          attribute :summary, String
+
+          def add_operation(method = nil, keywords = {}) # :nodoc:
+            try_modify_attribute!(:operations) do
+              method, keywords = nil, method if method.is_a?(Hash)
+              method = 'get' if method.nil?
+
+              (@operations ||= {})[method] = Operation.new(nil, keywords.merge(method: method))
+            end
+          end
+
+          def add_parameter(name, keywords = {}) # :nodoc:
+            try_modify_attribute!(:parameters) do
+              name = name.to_s
+
+              (@parameters ||= {})[name] = Parameter.new(name, keywords)
+            end
+          end
+
+          # Returns a hash representing the \OpenAPI path item object that describes
+          # the operations.
+          def to_openapi(version, definitions)
+            OpenAPI::PathItem.new(
+              operations.values,
+              description: description,
+              summary: summary,
+              parameters: parameters
+            ).to_openapi(version, definitions)
+          end
+        end
+
         ##
-        # :attr: operations
-        attribute :operations, { String => Operation }, accessors: %i[reader writer]
+        # :attr: expressions
+        attribute :expressions, { String => Operations }, accessors: %i[reader writer]
 
-        # Adds a callback operation.
+        # Adds an expression.
         #
         # Raises an +ArgumentError+ if +expression+ is blank.
-        def add_operation(expression, keywords = {})
-          raise ArgumentError, "expression can't be blank" if expression.blank?
+        def add_expression(expression, keywords = {})
+          try_modify_attribute!(:expressions) do
+            raise ArgumentError, "expression can't be blank" if expression.blank?
 
-          (@operations ||= {})[expression.to_s] = Operation.new(nil, keywords)
+            (@expressions ||= {})[expression.to_s] = Operations.new(keywords)
+          end
         end
 
         # Returns a hash representing the \OpenAPI callback object.
         def to_openapi(version, definitions)
-          operations.transform_values do |operation|
-            OpenAPI::PathItem.new([operation]).to_openapi(version, definitions)
+          expressions.transform_values do |operations|
+            operations.to_openapi(version, definitions)
           end
         end
       end

data/lib/jsapi/meta/content.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # Specifies the content of a request body or response.
+    class Content < Model::Base
+      include OpenAPI::Extensions
+
+      class Wrapper < Model::Wrapper
+        def schema
+          @schema ||= Schema.wrap(super, definitions)
+        end
+      end
+
+      include Model::Wrappable
+
+      delegate_missing_to :schema
+
+      ##
+      # :attr: examples
+      # The examples. Maps example names to Example objects or references.
+      attribute :examples, { String => Example }, default_key: 'default'
+
+      ##
+      # :attr_reader: schema
+      # The Schema of the content.
+      attribute :schema, accessors: %i[reader]
+
+      def initialize(keywords = {})
+        keywords = keywords.dup
+        super(keywords.extract!(:examples, :openapi_extensions))
+
+        add_example(value: keywords.delete(:example)) if keywords.key?(:example)
+        keywords[:ref] = keywords.delete(:schema) if keywords.key?(:schema)
+
+        @schema = Schema.new(keywords)
+      end
+
+      # Returns a hash representing the \OpenAPI media type object describing
+      # the content. Applies to \OpenAPI 3.0 and higher.
+      def to_openapi(version, media_type = nil)
+        version = OpenAPI::Version.from(version)
+
+        with_openapi_extensions(
+          **if media_type == Media::Type::APPLICATION_JSON_SEQ &&
+               schema.array? && version >= OpenAPI::V3_2
+              { itemSchema: schema.items.to_openapi(version) }
+            else
+              { schema: schema.to_openapi(version) }
+            end,
+          examples:
+            examples.transform_values do |example|
+              example.to_openapi(version)
+            end.presence
+        )
+      end
+    end
+  end
+end