jsapi 0.1.1

data/lib/jsapi/meta/parameter.rb

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

data/lib/jsapi/meta/property.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    class Property < Base
+      ##
+      # :attr_reader: name
+      # The name of the property.
+      attribute :name, writer: false
+
+      ##
+      # :attr: read_only
+      attribute :read_only, values: [true, false]
+
+      ##
+      # :attr_reader: schema
+      # The Schema of the parameter.
+      attribute :schema, writer: false
+
+      ##
+      # :attr: source
+      # The alternative method to read a property value when serializing
+      # an object.
+      attribute :source, Symbol
+
+      ##
+      # :attr: write_only
+      attribute :write_only, values: [true, false]
+
+      delegate_missing_to :schema
+
+      # Creates a new property.
+      #
+      # Raises an +ArgumentError+ if +name+ is blank.
+      def initialize(name, keywords = {})
+        raise ArgumentError, "property name can't be blank" if name.blank?
+
+        keywords = keywords.dup
+        super(keywords.extract!(:read_only, :source, :write_only))
+
+        @name = name.to_s
+        @schema = Schema.new(keywords)
+      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
+      end
+
+      # Returns a hash representing the \OpenAPI schema object.
+      def to_openapi(version)
+        version = OpenAPI::Version.from(version)
+
+        schema.to_openapi(version).tap do |hash|
+          hash[:readOnly] = true if read_only?
+          hash[:writeOnly] = true if write_only? && version.major > 2
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/reference_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    # Raised when a reference can't be resolved.
+    class ReferenceError < StandardError
+      def initialize(reference)
+        super("reference can't be resolved: '#{reference}'")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module RequestBody
+      class Model < Base
+        ##
+        # :attr: description
+        # The optional description of the request body.
+        attribute :description, String
+
+        ##
+        # :attr_reader: examples
+        # The optional examples.
+        attribute :examples, { String => Example }, default_key: 'default'
+
+        ##
+        # :attr_reader: schema
+        # The Schema of the parameter.
+        attribute :schema, writer: false
+
+        delegate_missing_to :schema
+
+        def initialize(keywords = {})
+          keywords = keywords.dup
+          super(keywords.extract!(:description, :examples))
+
+          add_example(value: keywords.delete(:example)) if keywords.key?(:example)
+
+          @schema = Schema.new(keywords)
+        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
+        end
+
+        # Returns a hash representing the \OpenAPI 2.0 parameter object.
+        def to_openapi_parameter
+          {
+            name: 'body',
+            in: 'body',
+            description: description,
+            required: required?
+          }.merge(schema.to_openapi('2.0')).compact
+        end
+
+        # Returns a hash representing the \OpenAPI 3.x request body object.
+        def to_openapi(version)
+          {
+            description: description,
+            content: {
+              'application/json' => {
+                schema: schema.to_openapi(version),
+                examples: examples&.transform_values(&:to_openapi)
+              }.compact
+            },
+            required: required?
+          }.compact
+        end
+      end
+    end
+  end
+end

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

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

data/lib/jsapi/meta/request_body.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'request_body/model'
+require_relative 'request_body/reference'
+
+module Jsapi
+  module Meta
+    module RequestBody
+      class << self
+        # Creates a new request body 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/rescue_handler.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    class RescueHandler
+      attr_reader :status
+
+      def initialize(klass, status: nil)
+        unless klass.is_a?(Class) && klass.ancestors.include?(StandardError)
+          raise ArgumentError, "#{klass.inspect} must be a standard error class"
+        end
+
+        @klass = klass
+        @status = status || 'default'
+      end
+
+      def inspect # :nodoc:
+        "#<#{self.class.name} class: #{@klass}, status: #{@status.inspect}>"
+      end
+
+      def match?(exception)
+        exception.is_a?(@klass)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Response
+      class Model < Base
+        ##
+        # :attr: description
+        # The optional description of the response.
+        attribute :description, String
+
+        ##
+        # :attr: examples
+        # The optional examples.
+        attribute :examples, { String => Example }, default_key: 'default'
+
+        ##
+        # :attr: links
+        # The optional OpenAPI::Link objects.
+        attribute :links, { String => OpenAPI::Link }
+
+        ##
+        # :attr: locale
+        # The locale used when rendering a response.
+        attribute :locale, Symbol
+
+        ##
+        # :attr_reader: schema
+        # The Schema of the parameter.
+        attribute :schema, writer: false
+
+        delegate_missing_to :schema
+
+        def initialize(keywords = {})
+          keywords = keywords.dup
+          super(keywords.extract!(:description, :examples, :locale))
+
+          add_example(value: keywords.delete(:example)) if keywords.key?(:example)
+
+          @schema = Schema.new(**keywords)
+        end
+
+        # Returns a hash representing the \OpenAPI response object.
+        def to_openapi(version, definitions)
+          version = OpenAPI::Version.from(version)
+          if version.major == 2
+            {
+              description: description,
+              schema: schema.to_openapi(version),
+              examples: (
+                if (example = examples&.values&.first).present?
+                  { 'application/json' => example.resolve(definitions).value }
+                end
+              )
+            }
+          else
+            {
+              description: description,
+              content: {
+                'application/json' => {
+                  schema: schema.to_openapi(version),
+                  examples: examples&.transform_values(&:to_openapi)
+                }.compact
+              },
+              links: links&.transform_values(&:to_openapi)
+            }
+          end.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Response
+      class Reference < BaseReference
+        # Returns a hash representing the \OpenAPI reference object.
+        def to_openapi(version, *)
+          version = OpenAPI::Version.from(version)
+          path = version.major == 2 ? 'responses' : 'components/responses'
+
+          { '$ref': "#/#{path}/#{ref}" }
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/response.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'response/model'
+require_relative 'response/reference'
+
+module Jsapi
+  module Meta
+    module Response
+      class << self
+        # Creates a new response 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/schema/array.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Schema
+      class Array < Base
+        ##
+        # :attr: items
+        # The Schema defining the kind of items.
+        attribute :items, Schema
+
+        ##
+        # :attr: max_items
+        # The maximum length of an array.
+        attribute :max_items, writer: false
+
+        ##
+        # :attr: min_items
+        # The minimum length of an array.
+        attribute :min_items, writer: false
+
+        def max_items=(value) # :nodoc:
+          add_validation('max_items', Validation::MaxItems.new(value))
+          @max_items = value
+        end
+
+        def min_items=(value) # :nodoc:
+          add_validation('min_items', Validation::MinItems.new(value))
+          @min_items = value
+        end
+
+        def to_json_schema # :nodoc:
+          super.merge(items: items&.to_json_schema || {})
+        end
+
+        def to_openapi(version) # :nodoc:
+          super.merge(items: items&.to_openapi(version) || {})
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Schema
+      class Base < Meta::Base
+        TYPES = %w[array boolean integer number object string].freeze # :nodoc:
+
+        TYPES.each do |type|
+          define_method("#{type}?") { self.type == type }
+        end
+
+        ##
+        # :attr: default
+        # The optional default value.
+        attribute :default
+
+        ##
+        # :attr: deprecated
+        # Specifies whether or not the schema is deprecated.
+        attribute :deprecated, values: [true, false]
+
+        ##
+        # :attr: description
+        # The optional description of the schema.
+        attribute :description, ::String
+
+        ##
+        # :attr: enum
+        # The allowed values.
+        attribute :enum, writer: false
+
+        ##
+        # :attr: examples
+        # The optional examples.
+        attribute :examples, [::Object]
+
+        ##
+        # :attr: external_docs
+        # The optional OpenAPI::ExternalDocumentation object.
+        attribute :external_docs, OpenAPI::ExternalDocumentation
+
+        ##
+        # :attr: existence
+        # The level of Existence. The default level of existence
+        # is +ALLOW_OMITTED+.
+        attribute :existence, Existence, default: Existence::ALLOW_OMITTED
+
+        ##
+        # :attr: title
+        # The optional title of the schema.
+        attribute :title, String
+
+        ##
+        # :attr_reader: type
+        # The type of the schema as a string.
+
+        # The validations.
+        attr_reader :validations
+
+        # Creates a new schema.
+        def initialize(keywords = {})
+          keywords = keywords.dup
+          add_example(keywords.delete(:example)) if keywords.key?(:example)
+
+          @type = keywords.delete(:type)
+          @validations = {}
+          super(keywords)
+        end
+
+        def enum=(value) # :nodoc:
+          add_validation('enum', Validation::Enum.new(value))
+          @enum = value
+        end
+
+        # Returns true if and only if values can be +null+ as specified
+        # by \JSON \Schema.
+        def nullable?
+          existence <= Existence::ALLOW_NIL
+        end
+
+        # Returns a hash representing the \JSON \Schema object.
+        def to_json_schema
+          {
+            type: nullable? ? [type, 'null'] : type,
+            title: title,
+            description: description,
+            default: default,
+            examples: examples.presence,
+            deprecated: deprecated?.presence
+          }.tap do |hash|
+            validations.each_value do |validation|
+              hash.merge!(validation.to_json_schema_validation)
+            end
+          end.compact
+        end
+
+        # Returns a hash representing the \OpenAPI schema object.
+        def to_openapi(version)
+          version = OpenAPI::Version.from(version)
+          if version.major == 2
+            # OpenAPI 2.0
+            {
+              type: type,
+              example: examples&.first
+            }
+          elsif version.minor.zero?
+            # OpenAPI 3.0
+            {
+              type: type,
+              nullable: nullable?.presence,
+              examples: examples,
+              deprecated: deprecated?.presence
+            }
+          else
+            # OpenAPI 3.1
+            {
+              type: nullable? ? [type, 'null'] : type,
+              examples: examples,
+              deprecated: deprecated?.presence
+            }
+          end.tap do |hash|
+            hash[:title] = title
+            hash[:description] = description
+            hash[:default] = default
+            hash[:externalDocs] = external_docs&.to_openapi
+
+            validations.each_value do |validation|
+              hash.merge!(validation.to_openapi_validation(version))
+            end
+          end.compact
+        end
+
+        def type # :nodoc:
+          @type ||= self.class.name.demodulize.downcase
+        end
+
+        private
+
+        def add_validation(keyword, validation)
+          validations[keyword] = validation
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Schema
+      class Boolean < Base; end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Schema
+      class Boundary
+        def self.from(value)
+          case value
+          when Boundary
+            value
+          when Hash
+            Boundary.new(value[:value], exclusive: value[:exclusive] == true)
+          else
+            Boundary.new(value)
+          end
+        end
+
+        # The value of the boundary.
+        attr_reader :value
+
+        def initialize(value, exclusive: false)
+          @value = value
+          @exclusive = exclusive
+        end
+
+        # Returns true if the boundary is exclusive, false otherwise.
+        def exclusive?
+          @exclusive == true
+        end
+
+        def inspect # :nodoc:
+          "#<#{self.class} value: #{value}, exclusive: #{exclusive?}>"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module Jsapi
+  module Meta
+    module Schema
+      module Conversion
+        extend ActiveSupport::Concern
+
+        included do
+          # The method or +Proc+ to convert objects by.
+          attr_accessor :conversion
+        end
+
+        def convert(object)
+          return object if conversion.nil?
+
+          if conversion.respond_to?(:call)
+            conversion.call(object)
+          else
+            object.send(conversion)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Schema
+      # Used by Reference to delegate method calls to the referred schema.
+      class Delegator
+        # The level of Existence.
+        attr_reader :existence
+
+        delegate_missing_to :@schema
+
+        def initialize(schema, existence)
+          @schema = schema
+          @existence = existence
+        end
+
+        def inspect # :nodoc:
+          "#<#{self.class.name} " \
+          "schema: #{@schema.inspect}, " \
+          "existence: #{@existence.inspect}>"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Schema
+      class Discriminator < Meta::Base
+        ##
+        # :attr: mappings
+        attribute :mappings, { String => String }
+
+        ##
+        # :attr: property_name
+        attribute :property_name, String
+
+        # Looks up the inherriting schema for +value+ in +definitions+.
+        def resolve(value, definitions)
+          schema = definitions.schema(mapping(value) || value)
+          raise "inherriting schema not found: #{value.inspect}" unless schema
+
+          schema.resolve(definitions)
+        end
+
+        # Returns a hash representing the \OpenAPI discriminator object.
+        def to_openapi(version)
+          version = OpenAPI::Version.from(version)
+          return property_name if version.major == 2
+
+          {
+            propertyName: property_name,
+            mapping: mappings
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Schema
+      class Integer < Numeric; end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Schema
+      class Number < Numeric; end
+    end
+  end
+end