jsapi 0.9.1 → 1.0

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Model
+      # The base reference class.
+      class Reference < Base
+        # Derrives the component type from the inner most module name.
+        def self.component_type
+          @component_type ||= name.split('::')[-2].underscore
+        end
+
+        # Derrives the \OpenAPI component type from the inner most module name.
+        def self.openapi_component_type
+          @openapi_component_type ||= name.split('::')[-2].pluralize.camelize(:lower)
+        end
+
+        ##
+        # :attr: description
+        # The description to be displayed instead of the description of the referred object.
+        # Applies to \OpenAPI 3.1 and higher.
+        attribute :description, String
+
+        ##
+        # :attr: ref
+        # The name of the referred object.
+        attribute :ref, String
+
+        ##
+        # :attr: summary
+        # The summary to be displayed instead of the summary of the referred object.
+        # Applies to \OpenAPI 3.1 and higher.
+        attribute :summary, String
+
+        # Returns true.
+        def reference?
+          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("find_#{self.class.component_type}", ref)
+          raise ReferenceError, ref if object.nil?
+
+          object.resolve(definitions)
+        end
+
+        # Returns a hash representing the \OpenAPI reference object.
+        def to_openapi(version, *)
+          version = OpenAPI::Version.from(version)
+
+          { '$ref': "#/#{openapi_components_path(version)}/#{ref}" }.tap do |result|
+            if version >= OpenAPI::V3_1
+              result[:summary] = summary if summary
+              result[:description] = description if description
+            end
+          end
+        end
+
+        private
+
+        def openapi_components_path(version)
+          component_type = self.class.openapi_component_type
+
+          version.major == 2 ? component_type : "components/#{component_type}"
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/{base → model}/type_caster.rb

@@ -2,7 +2,7 @@
 
 module Jsapi
   module Meta
-    module Base
+    module Model
       class TypeCaster
         STRING_CASTER = ->(arg) { arg&.to_s } # :nodoc:
 

data/lib/jsapi/meta/model.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative 'model/type_caster'
+require_relative 'model/attributes'
+require_relative 'model/base'
+require_relative 'model/reference'

data/lib/jsapi/meta/oauth_flow.rb

@@ -3,10 +3,10 @@
 module Jsapi
   module Meta
     # Represents an OAuth flow object.
-    class OAuthFlow < Base::Model
+    class OAuthFlow < Model::Base
       include OpenAPI::Extensions
 
-      class Scope < Base::Model
+      class Scope < Model::Base
         ##
         # :attr: description
         # The description of the scope.

data/lib/jsapi/meta/openapi/extensions.rb

@@ -4,35 +4,19 @@ module Jsapi
   module Meta
     module OpenAPI
       module Extensions
-        ##
-        # :attr: openapi_extensions
-        # The \OpenAPI extensions.
-
-        # Adds an \OpenAPI extension.
-        #
-        # Raises an +ArgumentError+ if +name+ is blank.
-        def add_openapi_extension(name, value = nil)
-          raise ArgumentError, "name can't be blank" if name.blank?
-
-          openapi_extensions["x-#{name}".to_sym] = value
-        end
-
-        def openapi_extensions # :nodoc:
-          @openapi_extensions ||= {}
-        end
-
-        def openapi_extensions=(extensions) # :nodoc:
-          @openapi_extensions = {}
-
-          extensions.each do |name, value|
-            add_openapi_extension(name, value)
-          end
+        def self.included(base) # :nodoc:
+          base.attribute :openapi_extensions, { String => String }
         end
 
         private
 
-        def with_openapi_extensions(keywords = {}) # :nodoc:
-          keywords.merge!(openapi_extensions)
+        def with_openapi_extensions(keywords = {})
+          keywords.merge!(
+            openapi_extensions.transform_keys do |key|
+              "x-#{key}".to_sym
+            end
+          ) if openapi_extensions.present?
+
           keywords.compact!
           keywords
         end

data/lib/jsapi/meta/openapi/version.rb

@@ -4,6 +4,8 @@ module Jsapi
   module Meta
     module OpenAPI
       class Version
+        include Comparable
+
         # Creates an \OpenAPI version from +version+.
         #
         # Raises an +ArgumentError+ if +version+ isn`t supported.
@@ -35,6 +37,15 @@ module Jsapi
             @minor == other.minor
         end
 
+        def <=>(other)
+          return unless other.is_a?(Version)
+
+          result = major <=> other.major
+          return result unless result.zero?
+
+          minor <=> other.minor
+        end
+
         def to_s # :nodoc:
           "#{major}.#{minor}"
         end

data/lib/jsapi/meta/openapi.rb

@@ -2,3 +2,13 @@
 
 require_relative 'openapi/extensions'
 require_relative 'openapi/version'
+
+module Jsapi
+  module Meta
+    module OpenAPI
+      V2_0 = Version.new(2, 0)
+      V3_0 = Version.new(3, 0)
+      V3_1 = Version.new(3, 1)
+    end
+  end
+end

data/lib/jsapi/meta/operation.rb

@@ -2,8 +2,8 @@
 
 module Jsapi
   module Meta
-    # Defines an API operation.
-    class Operation < Base::Model
+    # Specifies an API operation.
+    class Operation < Model::Base
       include OpenAPI::Extensions
 
       ##
@@ -43,18 +43,18 @@ module Jsapi
 
       ##
       # :attr: model
-      # The model class to access top-level parameters by. Model::Base by default.
-      attribute :model, Class, default: Model::Base
+      # The model class to access top-level parameters by, Jsapi::Model::Base by default.
+      attribute :model, Class, default: Jsapi::Model::Base
 
       ##
       # :attr_reader: name
       # The name of the operation.
-      attribute :name, read_only: true
+      attribute :name, accessors: %i[reader]
 
       ##
       # :attr: parameters
       # The parameters of the operation.
-      attribute :parameters, { String => Parameter }
+      attribute :parameters, { String => Parameter }, accessors: %i[reader writer]
 
       ##
       # :attr: path
@@ -110,8 +110,6 @@ module Jsapi
         super(keywords)
       end
 
-      undef add_parameter
-
       def add_parameter(name, keywords = {}) # :nodoc:
         (@parameters ||= {})[name.to_s] = Parameter.new(name, keywords)
       end
@@ -140,36 +138,36 @@ module Jsapi
           externalDocs: external_docs&.to_openapi,
           deprecated: deprecated?.presence,
           security: security_requirements.map(&:to_openapi).presence
-        ).tap do |hash|
+        ).tap do |result|
           if version.major == 2
             if (consumes = consumes(definitions)).present?
-              hash[:consumes] = [consumes]
+              result[:consumes] = [consumes]
             end
             if (produces = produces(definitions)).present?
-              hash[:produces] = produces
+              result[:produces] = produces
             end
-            hash[:schemes] = schemes if schemes.present?
+            result[:schemes] = schemes if schemes.present?
           elsif servers.present?
-            hash[:servers] = servers.map(&:to_openapi)
+            result[:servers] = servers.map(&:to_openapi)
           end
           # Parameters (and request body)
-          hash[:parameters] = parameters.values.flat_map do |parameter|
+          result[:parameters] = parameters.values.flat_map do |parameter|
             parameter.to_openapi_parameters(version, definitions)
           end
           if request_body
             if version.major == 2
-              hash[:parameters] << request_body.resolve(definitions).to_openapi_parameter
+              result[:parameters] << request_body.resolve(definitions).to_openapi_parameter
             else
-              hash[:request_body] = request_body.to_openapi(version)
+              result[:request_body] = request_body.to_openapi(version)
             end
           end
           # Responses
-          hash[:responses] = responses.transform_values do |response|
+          result[:responses] = responses.transform_values do |response|
             response.to_openapi(version, definitions)
           end
           # Callbacks
           if callbacks.present? && version.major > 2
-            hash[:callbacks] = callbacks.transform_values do |callback|
+            result[:callbacks] = callbacks.transform_values do |callback|
               callback.to_openapi(version, definitions)
             end
           end

data/lib/jsapi/meta/parameter/{model.rb → base.rb}

@@ -3,9 +3,8 @@
 module Jsapi
   module Meta
     module Parameter
-      # Defines a parameter.
-      class Model < Base::Model
-        include ToOpenAPI
+      # Specifies a parameter.
+      class Base < Model::Base
         include OpenAPI::Extensions
 
         delegate_missing_to :schema
@@ -39,12 +38,12 @@ module Jsapi
         ##
         # :attr_reader: name
         # The name of the parameter.
-        attribute :name, read_only: true
+        attribute :name, accessors: %i[reader]
 
         ##
         # :attr_reader: schema
         # The Schema of the parameter.
-        attribute :schema, read_only: true
+        attribute :schema, accessors: %i[reader]
 
         # Creates a new parameter.
         #
@@ -63,25 +62,40 @@ module Jsapi
           @schema = Schema.new(keywords)
         end
 
-        # Returns true if empty values are allowed as specified by \OpenAPI,
-        # false otherwise.
+        # Returns true if empty values are allowed as specified by \OpenAPI, false otherwise.
         def allow_empty_value?
-          schema.existence <= Existence::ALLOW_EMPTY && self.in != 'path'
+          schema.existence <= Existence::ALLOW_EMPTY && self.in == 'query'
         end
 
-        # Returns true if it is required as specified by \JSON \Schema,
-        # false otherwise.
+        # Returns true if it is required as specified by \JSON \Schema, false otherwise.
         def required?
           schema.existence > Existence::ALLOW_OMITTED || self.in == 'path'
         end
 
+        # 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(
+            name,
+            schema,
+            version,
+            description: description,
+            required: required?,
+            deprecated: deprecated?,
+            allow_empty_value: allow_empty_value?,
+            examples: examples
+          )
+        end
+
         # Returns an array of hashes representing the \OpenAPI parameter objects.
         def to_openapi_parameters(version, definitions)
           version = OpenAPI::Version.from(version)
           schema = self.schema.resolve(definitions)
 
           if schema.object?
-            explode_object_parameter(
+            explode_parameter(
               name,
               schema,
               version,
@@ -90,35 +104,16 @@ module Jsapi
               deprecated: deprecated?
             )
           else
-            parameter_name = schema.array? ? "#{name}[]" : name
             [
-              with_openapi_extensions(
-                if version.major == 2
-                  {
-                    name: parameter_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: parameter_name,
-                    in: self.in,
-                    description: description,
-                    required: required?.presence,
-                    allowEmptyValue: allow_empty_value?.presence,
-                    deprecated: deprecated?.presence,
-                    schema: schema.to_openapi(version),
-                    examples: examples.transform_values(&:to_openapi).presence
-
-                    # NOTE: collectionFormat is replaced by style and explode.
-                    #       The default values for query parameters are:
-                    #       - style: 'form'
-                    #       - explode: true
-                  }
-                end
+              openapi_parameter(
+                name,
+                schema,
+                version,
+                description: description,
+                required: required?,
+                deprecated: deprecated?,
+                allow_empty_value: allow_empty_value?,
+                examples: examples
               )
             ]
           end
@@ -126,16 +121,15 @@ module Jsapi
 
         private
 
-        def explode_object_parameter(name, schema, version, definitions, **options)
+        def explode_parameter(name, schema, version, definitions, required:, deprecated:)
           schema.resolve_properties(definitions, context: :request).values.flat_map do |property|
             property_schema = property.schema.resolve(definitions)
             parameter_name = "#{name}[#{property.name}]"
-
-            required = (property.required? && options[:required]).presence
-            deprecated = (property.deprecated? || options[:deprecated]).presence
+            required = (required && property.required?).presence
+            deprecated = (deprecated || property.deprecated?).presence
 
             if property_schema.object?
-              explode_object_parameter(
+              explode_parameter(
                 parameter_name,
                 property_schema,
                 version,
@@ -144,37 +138,60 @@ module Jsapi
                 deprecated: deprecated
               )
             else
-              parameter_name = "#{parameter_name}[]" if property_schema.array?
-              description = property_schema.description
-              allow_empty_value = property.schema.existence <= Existence::ALLOW_EMPTY
               [
-                with_openapi_extensions(
-                  if version.major == 2
-                    {
-                      name: parameter_name,
-                      in: self.in,
-                      description: description,
-                      required: required,
-                      allowEmptyValue: allow_empty_value.presence,
-                      collectionFormat: ('multi' if property_schema.array?)
-                    }.merge(property_schema.to_openapi(version))
-                  else
-                    {
-                      name: parameter_name,
-                      in: self.in,
-                      description: description,
-                      required: required,
-                      allowEmptyValue: allow_empty_value.presence,
-                      deprecated: deprecated,
-                      schema: property_schema.to_openapi(version).except(:deprecated),
-                      examples: examples.transform_values(&:to_openapi).presence
-                    }
-                  end
+                openapi_parameter(
+                  parameter_name,
+                  property_schema,
+                  version,
+                  description: property_schema.description,
+                  required: required,
+                  deprecated: deprecated,
+                  allow_empty_value: property.schema.existence <= Existence::ALLOW_EMPTY
                 )
               ]
             end
           end
         end
+
+        def openapi_parameter(name, schema, version,
+                              allow_empty_value:,
+                              deprecated:,
+                              description:,
+                              required:,
+                              examples: nil)
+
+          name = schema.array? ? "#{name}[]" : name
+
+          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
+          )
+        end
       end
     end
   end

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

@@ -3,12 +3,9 @@
 module Jsapi
   module Meta
     module Parameter
-      class Reference < Base::Reference
-        include ToOpenAPI
-
-        # Returns an array of hashes. Each hash represents an \OpenAPI parameter object
-        # if the type of the referred parameter is <code>"object"</code>. Otherwise the
-        # array contains a single hash representing the \OpenAPI reference object.
+      # Refers a reusable parameter.
+      class Reference < Model::Reference
+        # Returns an array of hashes representing the \OpenAPI parameter or reference objects.
         #
         # Raises a ReferenceError when the reference could not be resolved.
         def to_openapi_parameters(version, definitions)
@@ -20,9 +17,7 @@ module Jsapi
             parameter.to_openapi_parameters(version, definitions)
           else
             # Return an array containing the reference object
-            path = version.major == 2 ? 'parameters' : 'components/parameters'
-
-            [{ '$ref': "#/#{path}/#{ref}" }]
+            [to_openapi(version)]
           end
         end
       end

data/lib/jsapi/meta/parameter.rb

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

data/lib/jsapi/meta/property.rb

@@ -2,13 +2,14 @@
 
 module Jsapi
   module Meta
-    class Property < Base::Model
+    # Specifies a property
+    class Property < Model::Base
       delegate_missing_to :schema
 
       ##
       # :attr_reader: name
       # The name of the property.
-      attribute :name, read_only: true
+      attribute :name, accessors: %i[reader]
 
       ##
       # :attr: read_only
@@ -17,7 +18,7 @@ module Jsapi
       ##
       # :attr_reader: schema
       # The Schema of the parameter.
-      attribute :schema, read_only: true
+      attribute :schema, accessors: %i[reader]
 
       ##
       # :attr: source
@@ -59,9 +60,9 @@ module Jsapi
       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
+        schema.to_openapi(version).tap do |result|
+          result[:readOnly] = true if read_only?
+          result[:writeOnly] = true if write_only? && version.major > 2
         end
       end
     end

data/lib/jsapi/meta/request_body/{model.rb → base.rb}

@@ -3,8 +3,8 @@
 module Jsapi
   module Meta
     module RequestBody
-      # Defines a request body.
-      class Model < Base::Model
+      # Specifies a request body.
+      class Base < Model::Base
         include OpenAPI::Extensions
 
         delegate_missing_to :schema
@@ -27,7 +27,7 @@ module Jsapi
         ##
         # :attr_reader: schema
         # The Schema of the request body.
-        attribute :schema, read_only: true
+        attribute :schema, accessors: %i[reader]
 
         def initialize(keywords = {})
           keywords = keywords.dup
@@ -47,12 +47,14 @@ module Jsapi
 
         # 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')).merge(openapi_extensions).compact
+          with_openapi_extensions(
+            {
+              name: 'body',
+              in: 'body',
+              description: description,
+              required: required?
+            }.merge(schema.to_openapi(OpenAPI::V2_0))
+          )
         end
 
         # Returns a hash representing the \OpenAPI 3.x request body object.

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

@@ -3,12 +3,8 @@
 module Jsapi
   module Meta
     module RequestBody
-      class Reference < Base::Reference
-        # Returns a hash representing the \OpenAPI reference object.
-        def to_openapi(*)
-          { '$ref': "#/components/requestBodies/#{ref}" }
-        end
-      end
+      # Refers a reusable request body.
+      class Reference < Model::Reference; end
     end
   end
 end

data/lib/jsapi/meta/request_body.rb

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