jsapi 0.1.1

data/lib/jsapi/meta/attributes/class_methods.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Attributes
+      module ClassMethods
+        # Defines an attribute.
+        def attribute(name, type = Object,
+                      keys: nil,
+                      values: nil,
+                      default: nil,
+                      default_key: nil,
+                      writer: true)
+
+          (@attribute_names ||= []) << name.to_sym
+
+          instance_variable_name = "@#{name}"
+
+          # Attribute reader
+          define_method(name) do
+            value = instance_variable_get(instance_variable_name)
+            value.nil? ? default : value
+          end
+
+          case type
+          when Array
+            if writer
+              singular_name = name.to_s.singularize
+              type_caster = TypeCaster.new(type.first, values: values, name: singular_name)
+
+              # Attribute writer
+              define_method("#{name}=") do |argument|
+                instance_variable_set(
+                  instance_variable_name,
+                  Array.wrap(argument).map { |element| type_caster.cast(element) }
+                )
+              end
+
+              # add_{singular_name} method
+              define_method("add_#{singular_name}") do |argument = nil|
+                type_caster.cast(argument).tap do |casted_argument|
+                  if instance_variable_defined?(instance_variable_name)
+                    instance_variable_get(instance_variable_name)
+                  else
+                    instance_variable_set(instance_variable_name, [])
+                  end << casted_argument
+                end
+              end
+            end
+          when Hash
+            singular_name = name.to_s.singularize
+            key_type, value_type = type.first
+            key_type_caster = TypeCaster.new(key_type, values: keys, name: 'key')
+
+            # hash value reader
+            define_method(singular_name) do |key = nil|
+              send(name)&.[](key_type_caster.cast(key) || default_key)
+            end
+
+            if writer
+              value_type_caster = TypeCaster.new(value_type, values: values)
+
+              # add_{singular_name} method
+              define_method("add_#{singular_name}") do |key_or_value, value = nil|
+                if value.nil? && default_key
+                  key = default_key
+                  value = key_or_value
+                else
+                  key = key_or_value || default_key
+                end
+                raise ArgumentError, "key can't be blank" if key.blank?
+
+                casted_key = key_type_caster.cast(key)
+                casted_value = value_type_caster.cast(value)
+
+                if instance_variable_defined?(instance_variable_name)
+                  instance_variable_get(instance_variable_name)
+                else
+                  instance_variable_set(instance_variable_name, {})
+                end[casted_key] = casted_value
+              end
+            end
+          else
+            # Predicate method
+            define_method("#{name}?") do
+              value = instance_variable_get(instance_variable_name)
+              value.nil? ? default || false : value
+            end if values == [true, false]
+
+            if writer
+              type_caster = TypeCaster.new(type, values: values, name: name)
+
+              # Attribute writer
+              define_method("#{name}=") do |argument = nil|
+                instance_variable_set(
+                  instance_variable_name, type_caster.cast(argument)
+                )
+              end
+            end
+          end
+        end
+
+        def attribute_names
+          names = @attribute_names || []
+          return names unless superclass.respond_to?(:attribute_names)
+
+          superclass.attribute_names + names
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/attributes/type_caster.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Attributes
+      class TypeCaster
+        STRING_CASTER = ->(arg) { arg&.to_s } # :nodoc:
+
+        SYMBOL_CASTER = ->(arg) { # :nodoc:
+          return if arg.nil?
+
+          arg = arg.to_s unless arg.respond_to?(:to_sym)
+          arg.to_sym
+        }
+
+        # Creates a new type caster for +klass+.
+        def initialize(klass, name: 'value', values: nil)
+          @caster =
+            case klass.name
+            when 'String'
+              STRING_CASTER
+            when 'Symbol'
+              SYMBOL_CASTER
+            else
+              ->(arg) {
+                return arg if arg.is_a?(klass)
+                return klass.from(arg) if klass.respond_to?(:from)
+                return klass.new if arg.nil?
+
+                klass.new(arg)
+              }
+            end
+          @values = values
+          @name = name
+        end
+
+        # Casts +value+. Raises an InvalidArgumentError if the (casted)
+        # value is invalid.
+        def cast(value)
+          casted_value = @caster.call(value)
+          return casted_value unless @values&.exclude?(casted_value)
+
+          raise InvalidArgumentError.new(@name, casted_value, @values)
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/attributes.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative 'attributes/type_caster'
+require_relative 'attributes/class_methods'

data/lib/jsapi/meta/base.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # The base meta model class.
+    class Base
+      extend Attributes::ClassMethods
+
+      # Creates a new meta model. Raises an +ArgumentError+ if at least one
+      # keyword is not supported.
+      def initialize(keywords = {})
+        keywords.each do |key, value|
+          if respond_to?(method = "#{key}=")
+            public_send(method, value)
+          else
+            raise ArgumentError, "unsupported keyword: #{key}"
+          end
+        end
+      end
+
+      def inspect # :nodoc:
+        klass = self.class
+        "#<#{klass.name} #{
+          klass.attribute_names.map do |name|
+            "#{name}: #{send(name).inspect}"
+          end.join(', ')
+        }>"
+      end
+
+      # Returns true if and only if this is a reference.
+      def reference?
+        false
+      end
+
+      # Returns itself.
+      def resolve(*)
+        self
+      end
+    end
+  end
+end

data/lib/jsapi/meta/base_reference.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    class BaseReference < Base
+      ##
+      # :attr: ref
+      # The name of the referred object.
+      attribute :ref, String
+
+      # Returns the name of the method to be invoked to look up the referred
+      # object in a Definitions instance.
+      def self.lookup_method_name
+        @lookup_method_name ||=
+          name.delete_suffix('::Reference').demodulize.underscore
+      end
+
+      def reference? # :nodoc:
+        true
+      end
+
+      # Resolves +ref+ by looking up the object with that name in +definitions+.
+      #
+      # Raises a ReferenceError if +ref+ could not be resolved.
+      def resolve(definitions)
+        object = definitions.send(self.class.lookup_method_name, ref)
+        raise ReferenceError, ref if object.nil?
+
+        object.resolve(definitions)
+      end
+    end
+  end
+end

data/lib/jsapi/meta/definitions.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    class Definitions
+      attr_reader :examples, :openapi_root, :operations, :parameters,
+                  :request_bodies, :rescue_handlers, :responses, :schemas
+
+      def initialize(owner = nil)
+        @owner = owner
+        @examples = {}
+        @operations = {}
+        @parameters = {}
+        @request_bodies = {}
+        @responses = {}
+        @schemas = {}
+        @rescue_handlers = []
+        @self_and_included = [self]
+      end
+
+      def add_example(name, keywords = {})
+        @examples[name.to_s] = Example.new(keywords)
+      end
+
+      def add_operation(name = nil, keywords = {})
+        name = name.nil? ? default_operation_name : name.to_s
+        @operations[name] = Operation.new(name, keywords.reverse_merge(path: default_path))
+      end
+
+      def add_parameter(name, keywords = {})
+        name = name.to_s
+        @parameters[name] = Parameter.new(name, keywords)
+      end
+
+      def add_request_body(name, keywords = {})
+        @request_bodies[name.to_s] = RequestBody.new(keywords)
+      end
+
+      def add_rescue_handler(klass, status: nil)
+        @rescue_handlers << RescueHandler.new(klass, status: status)
+      end
+
+      def add_response(name, keywords = {})
+        name = name.to_s
+        @responses[name] = Response.new(keywords)
+      end
+
+      def add_schema(name, keywords = {})
+        name = name.to_s
+        @schemas[name] = Schema.new(keywords)
+      end
+
+      def example(name)
+        return unless (name = name.to_s).present?
+
+        definitions = @self_and_included.find { |d| d.examples.key?(name) }
+        definitions.examples[name] if definitions
+      end
+
+      def include(definitions)
+        return if @self_and_included.include?(definitions)
+
+        @self_and_included << definitions
+      end
+
+      def inspect # :nodoc:
+        "#<#{self.class.name} #{
+          %i[owner operations parameters request_bodies responses schemas
+             examples openapi_root rescue_handlers].map do |name|
+            "#{name}: #{instance_variable_get("@#{name}").inspect}"
+          end.join(', ')
+        }>"
+      end
+
+      # Returns the JSON Schema document for the given schema as a +Hash+.
+      def json_schema_document(name)
+        schema(name)&.to_json_schema&.tap do |hash|
+          definitions =
+            @self_and_included
+            .map(&:schemas)
+            .reduce(&:merge)
+            .except(name.to_s)
+            .transform_values(&:to_json_schema)
+
+          hash[:definitions] = definitions if definitions.any?
+        end
+      end
+
+      # Returns a hash representing the OpenAPI document for +version+.
+      # Raises an +ArgumentError+ if +version+ is not supported.
+      def openapi_document(version = nil)
+        version = OpenAPI::Version.from(version)
+
+        (openapi_root&.to_openapi(version, self) || {}).tap do |h|
+          h[:paths] = openapi_paths(version)
+
+          if version.major == 2
+            h.merge!(
+              definitions: openapi_schemas(version),
+              parameters: openapi_parameters(version),
+              responses: openapi_responses(version)
+            )
+          else
+            h.deep_merge!(
+              components: {
+                schemas: openapi_schemas(version),
+                parameters: openapi_parameters(version),
+                requestBodies: openapi_request_bodies(version),
+                responses: openapi_responses(version),
+                examples: openapi_examples
+              }.compact.presence
+            )
+          end
+        end.compact
+      end
+
+      def openapi_root=(keywords = {})
+        @openapi_root = OpenAPI::Root.new(**keywords)
+      end
+
+      def operation(name = nil)
+        if (name = name.to_s).present?
+          definitions = @self_and_included.find { |d| d.operations.key?(name) }
+          definitions.operations[name] if definitions
+        elsif @operations.one?
+          # return the one and only operation
+          @operations.values.first
+        end
+      end
+
+      def parameter(name)
+        return unless (name = name.to_s).present?
+
+        definitions = @self_and_included.find { |d| d.parameters.key?(name) }
+        definitions.parameters[name] if definitions
+      end
+
+      def request_body(name)
+        return unless (name = name.to_s).present?
+
+        definitions = @self_and_included.find { |d| d.request_bodies.key?(name) }
+        definitions.request_bodies[name] if definitions
+      end
+
+      def rescue_handler_for(exception)
+        @self_and_included.each do |definitions|
+          definitions.rescue_handlers.each do |rescue_handler|
+            return rescue_handler if rescue_handler.match?(exception)
+          end
+        end
+        nil
+      end
+
+      def response(name)
+        return unless (name = name.to_s).present?
+
+        definitions = @self_and_included.find { |d| d.responses.key?(name) }
+        definitions.responses[name] if definitions
+      end
+
+      def schema(name)
+        return unless (name = name.to_s).present?
+
+        definitions = @self_and_included.find { |d| d.schemas.key?(name) }
+        definitions.schemas[name] if definitions
+      end
+
+      private
+
+      def default_operation_name
+        @default_operation_name ||= @owner.to_s.demodulize.delete_suffix('Controller').underscore
+      end
+
+      def default_path
+        @default_path ||= "/#{default_operation_name}"
+      end
+
+      def openapi_examples
+        @self_and_included
+          .map(&:examples).reduce(&:merge)
+          .transform_values(&:to_openapi)
+          .presence
+      end
+
+      def openapi_parameters(version)
+        @self_and_included
+          .map(&:parameters).reduce(&:merge)
+          .transform_values do |parameter|
+          parameter.to_openapi(version, self).first
+        end.presence
+      end
+
+      def openapi_paths(version)
+        @self_and_included
+          .map(&:operations).reduce(&:merge).values
+          .group_by { |operation| operation.path || default_path }
+          .transform_values do |operations|
+          operations.index_by(&:method).transform_values do |operation|
+            operation.to_openapi(version, self)
+          end
+        end.presence
+      end
+
+      def openapi_request_bodies(version)
+        @self_and_included
+          .map(&:request_bodies).reduce(&:merge).transform_values do |request_body|
+            request_body.to_openapi(version)
+          end.presence
+      end
+
+      def openapi_responses(version)
+        @self_and_included
+          .map(&:responses).reduce(&:merge).transform_values do |response|
+          response.to_openapi(version, self)
+        end.presence
+      end
+
+      def openapi_schemas(version)
+        @self_and_included
+          .map(&:schemas).reduce(&:merge).transform_values do |schema|
+          schema.to_openapi(version)
+        end.presence
+      end
+    end
+  end
+end

data/lib/jsapi/meta/example/model.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Example
+      class Model < Base
+        ##
+        # :attr: description
+        # The optional description of the example.
+        attribute :description, String
+
+        ##
+        # :attr: external
+        # If true, +value+ is interpreted as a URI pointing to an external
+        # sample value.
+        attribute :external, values: [true, false]
+
+        ##
+        # :attr: summary
+        # The optional summary of the example.
+        attribute :summary, String
+
+        ##
+        # :attr: value
+        # The sample value.
+        attribute :value
+
+        # Returns a hash representing the \OpenAPI example object.
+        def to_openapi(*)
+          {}.tap do |hash|
+            hash[:summary] = summary if summary.present?
+            hash[:description] = description if description.present?
+
+            if external?
+              hash[:external_value] = value
+            else
+              hash[:value] = value
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Example
+      class Reference < BaseReference
+        # Returns a hash representing the \OpenAPI reference object.
+        def to_openapi(*)
+          { '$ref': "#/components/examples/#{ref}" }
+        end
+      end
+    end
+  end
+end
+

data/lib/jsapi/meta/example.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'example/model'
+require_relative 'example/reference'
+
+module Jsapi
+  module Meta
+    module Example
+      class << self
+        # Creates a new example model or reference.
+        def new(keywords = {})
+          return Reference.new(keywords) if keywords.key?(:ref)
+
+          Model.new(keywords)
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/existence.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # Combines the presence concepts of the +#present?+ method and \JSON \Schema
+    # by four levels of existence.
+    class Existence
+      include Comparable
+
+      # The level of existence.
+      attr_reader :level
+
+      # Creates a new instance with the specified level.
+      def initialize(level)
+        @level = level
+      end
+
+      # The parameter or property can be omitted, corresponds to the opposite
+      # of +required+ as specified by \JSON \Schema.
+      ALLOW_OMITTED = new(1)
+
+      # The parameter or property value can be +nil+, corresponds to
+      # <code>nullable: true</code> as specified by \JSON \Schema.
+      ALLOW_NIL = new(2)
+
+      # The parameter or property value must respond to +nil?+ with +false+.
+      ALLOW_EMPTY = new(3)
+
+      # The parameter or property value must respond to +present?+ with +true+
+      # or must be +false+.
+      PRESENT = new(4)
+
+      # Creates a new instance from +value+.
+      def self.from(value)
+        return value if value.is_a?(Existence)
+
+        case value
+        when :present, true
+          PRESENT
+        when :allow_empty
+          ALLOW_EMPTY
+        when :allow_nil, :allow_null
+          ALLOW_NIL
+        when :allow_omitted, false, nil
+          ALLOW_OMITTED
+        else
+          raise ArgumentError, "invalid existence: #{value}"
+        end
+      end
+
+      def ==(other) # :nodoc:
+        other.is_a?(Existence) && level == other.level
+      end
+
+      def <=>(other) # :nodoc:
+        level <=> other.level
+      end
+
+      def inspect # :nodoc:
+        "#<#{self.class.name} level: #{level}>"
+      end
+
+      # Returns true if +object+ reaches the level of existence, false otherwise.
+      def reach?(object)
+        (object.null? ? 2 : object.empty? ? 3 : 4) >= level
+      end
+    end
+  end
+end

data/lib/jsapi/meta/invalid_argument_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    class InvalidArgumentError < ArgumentError
+      def initialize(name, value, values)
+        super("#{name} must be one of #{values.inspect}, is #{value.inspect}")
+      end
+    end
+  end
+end

data/lib/jsapi/meta/openapi/callback/model.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module Callback
+        # Represents a callback object. Applies to \OpenAPI 3.x.
+        class Model < Base
+          ##
+          # :attr: operations
+          attribute :operations, writer: false, default: {}
+
+          # Adds a callback operation.
+          #
+          # Raises an +ArgumentError+ if +expression+ is blank.
+          def add_operation(expression, keywords = {})
+            raise ArgumentError, "expression can't be blank" if expression.blank?
+
+            (@operations ||= {})[expression.to_s] = Operation.new(nil, keywords)
+          end
+
+          def operation(expression) # :nodoc:
+            @operations&.[](expression&.to_s)
+          end
+
+          # Returns a hash representing the callback object.
+          def to_openapi(version, definitions)
+            operations.transform_values do |operation|
+              { operation.method => operation.to_openapi(version, definitions) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/openapi/callback/reference.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      module Callback
+        class Reference < BaseReference
+          # Returns a hash representing the \OpenAPI reference object.
+          def to_openapi(*)
+            { '$ref': "#/components/callbacks/#{ref}" }
+          end
+        end
+      end
+    end
+  end
+end