jsapi 1.4 → 2.0

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Model
+      # Wraps a meta model
+      class Wrapper < SimpleDelegator
+        attr_reader :definitions
+
+        def initialize(model, definitions)
+          super(model.resolve(definitions))
+          @definitions = definitions
+        end
+
+        def ==(other) # :nodoc:
+          other.is_a?(self.class) &&
+            __getobj__ == other.__getobj__
+        end
+
+        def inspect # :nodoc:
+          "#<#{self.class.name} #{super}>"
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/model.rb

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

data/lib/jsapi/meta/oauth_flow.rb

@@ -36,7 +36,7 @@ module Jsapi
 
       ##
       # :attr: scopes
-      # The hash containing the scopes.
+      # The scopes. Maps strings to Scope objects.
       attribute :scopes, { String => Scope }
 
       ##

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

@@ -11,12 +11,11 @@ module Jsapi
         private
 
         def with_openapi_extensions(keywords = {})
-          keywords.merge!(
-            openapi_extensions.transform_keys do |key|
-              "x-#{key}".to_sym
-            end
-          ) if openapi_extensions.present?
-
+          if openapi_extensions.present?
+            keywords.merge!(
+              openapi_extensions.transform_keys { |key| "x-#{key}" }
+            )
+          end
           keywords.compact!
           keywords
         end

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

@@ -6,9 +6,9 @@ module Jsapi
       class Version
         include Comparable
 
-        # Creates an \OpenAPI version from +version+.
+        # Transforms +version+ to an instance of this class.
         #
-        # Raises an +ArgumentError+ if +version+ isn`t supported.
+        # Raises an +ArgumentError+ if +version+ could not be transformed.
         def self.from(version)
           return version if version.is_a?(Version)
 
@@ -48,13 +48,25 @@ module Jsapi
           minor <=> other.minor
         end
 
-        def inspect
+        def inspect # :nodoc:
           "<#{self.class.name} #{self}>"
         end
 
         def to_s # :nodoc:
-          "#{major}.#{minor}"
+          @to_s ||=
+            case [major, minor]
+            when [3, 0]
+              '3.0.4'
+            when [3, 1]
+              '3.1.2'
+            when [3, 2]
+              '3.2.0'
+            else
+              "#{major}.#{minor}"
+            end
         end
+
+        alias as_json to_s
       end
     end
   end

data/lib/jsapi/meta/operation.rb

@@ -6,14 +6,101 @@ module Jsapi
     class Operation < Model::Base
       include OpenAPI::Extensions
 
+      class Wrapper < Model::Wrapper
+        # Returns the most appropriate response for +status_code+.
+        def find_response(status_code)
+          status_code = Status::Code.from(status_code)
+
+          responses.find do |status, _response|
+            status.match?(status_code)
+          end&.second
+        end
+
+        def full_path # :nodoc:
+          @full_path ||= super
+        end
+
+        ##
+        # :attr_reader: model
+        # The model class of the wrapped operation or the default model class
+        # for the path.
+
+        # -
+        def model
+          return @model if defined? @model
+
+          @model = super || definitions.common_model(full_path)
+        end
+
+        ##
+        # :attr_reader: parameters
+        # The parameters of the wrapped operation in combination with the
+        # parameters applying to all operations in the path.
+
+        # -
+        def parameters
+          @parameters ||=
+            (definitions.common_parameters(full_path)&.merge(super) || super)
+            .transform_values { |parameter| Parameter.wrap(parameter, definitions) }
+        end
+
+        ##
+        # :attr_reader: request_body
+        # The request body of the wrapped operation or the default request
+        # body for the path.
+
+        # -
+        def request_body
+          return @request_body if defined? @request_body
+
+          @request_body = RequestBody.wrap(
+            (super || definitions.common_request_body(full_path)),
+            definitions
+          )
+        end
+
+        ##
+        # :attr_reader: responses
+        # The responses of the wrapped operation in combination with the
+        # responses applying to all operations in the path.
+
+        # -
+        def responses
+          @responses ||=
+            (definitions.common_responses(full_path)&.merge(super) || super)
+            .transform_values { |response| Response.wrap(response, definitions) }
+            .sort_by { |status, _response| status }
+            .to_h
+        end
+
+        ##
+        # :attr_reader: security_requirements
+        # The security requirements of the wrapped operation in combination
+        # with the security requirements applying to all operations in the
+        # path or the default security requirements.
+
+        # -
+        def security_requirements
+          return @security_requirements if defined? @security_requirements
+
+          @security_requirements =
+            [definitions.common_security_requirements(full_path), super]
+              .compact.presence&.flatten ||
+              definitions.default_security_requirements
+        end
+      end
+
+      include Model::Wrappable
+
       ##
       # :attr: callbacks
-      # The Callback objects. Applies to \OpenAPI 3.0 and higher.
+      # The callbacks that can be triggered by the operation. Maps strings
+      # to Callback objects or references.
       attribute :callbacks, { String => Callback }
 
       ##
       # :attr: deprecated
-      # Specifies whether or not the operation is deprecated.
+      # Specifies whether the operation is marked as deprecated.
       attribute :deprecated, values: [true, false]
 
       ##
@@ -23,7 +110,9 @@ module Jsapi
 
       ##
       # :attr: external_docs
-      # The ExternalDocumentation object.
+      # The additional external documentation for this operation.
+      #
+      # See ExternalDocumentation for further information.
       attribute :external_docs, ExternalDocumentation
 
       ##
@@ -33,8 +122,8 @@ module Jsapi
 
       ##
       # :attr: model
-      # The model class to access top-level parameters by, Jsapi::Model::Base by default.
-      attribute :model, Class, default: Jsapi::Model::Base
+      # The model class to access top-level parameters by.
+      attribute :model, Class
 
       ##
       # :attr_reader: name
@@ -43,7 +132,8 @@ module Jsapi
 
       ##
       # :attr: parameters
-      # The parameters of the operation.
+      # The parameters of the operation. Maps parameter names to Parameter
+      # objects or references.
       attribute :parameters, { String => Parameter }, accessors: %i[reader writer]
 
       ##
@@ -58,17 +148,19 @@ module Jsapi
 
       ##
       # :attr: request_body
-      # The request body of the operation.
+      # The request body of the operation as a RequestBody object or reference.
       attribute :request_body, RequestBody
 
       ##
       # :attr: responses
-      # The responses of the operation.
-      attribute :responses, { String => Response }, default_key: 'default'
+      # The responses that can be produced by the operation. Maps instances of
+      # Status::Base to Response objects or references.
+      attribute :responses, { Status => Response }, default_key: Status::DEFAULT
 
       ##
       # :attr: schemes
-      # The transfer protocols supported by the operation. Possible values are:
+      # The transfer protocols supported by the operation. Can contain one or
+      # more of:
       #
       # - <code>"http"</code>
       # - <code>"https"</code>
@@ -80,14 +172,20 @@ module Jsapi
 
       ##
       # :attr: security_requirements
-      # The SecurityRequirement objects.
-      attribute :security_requirements, [SecurityRequirement]
+      # The security requirements that override the top-level security requirements.
+      #
+      # See SecurityRequirement for further information.
+      attribute :security_requirements, [SecurityRequirement], default: :nil
 
       alias add_security add_security_requirement
 
       ##
       # :attr: servers
-      # The Server objects. Applies to \OpenAPI 3.0 and higher.
+      # The servers providing the operation.
+      #
+      # Applies to \OpenAPI 3.0 and higher.
+      #
+      # See Server for further information.
       attribute :servers, [Server]
 
       ##
@@ -109,7 +207,11 @@ module Jsapi
       end
 
       def add_parameter(name, keywords = {}) # :nodoc:
-        (@parameters ||= {})[name.to_s] = Parameter.new(name, keywords)
+        try_modify_attribute!(:parameters) do
+          name = name.to_s
+
+          (@parameters ||= {})[name.to_s] = Parameter.new(name, keywords)
+        end
       end
 
       # Returns the full path of the operation as a Pathname.
@@ -117,73 +219,77 @@ module Jsapi
         parent_path + path
       end
 
-      # Returns the MIME type consumed by the operation.
-      def consumes(definitions)
-        request_body&.resolve(definitions)&.content_type
-      end
-
-      # Returns an array containing the MIME types produced by the operation.
-      def produces(definitions)
-        responses.values.filter_map do |response|
-          response.resolve(definitions).content_type
-        end.uniq.sort
-      end
-
-      # Merges the parameters of this operation and the common parameters of all
-      # parent pathes and resolves them.
-      def resolved_parameters(definitions)
-        (definitions.path_parameters(full_path).presence&.merge(parameters) || parameters)
-          .transform_values { |parameter| parameter.resolve(definitions) }
-      end
-
       # Returns a hash representing the \OpenAPI operation object.
       def to_openapi(version, definitions)
         version = OpenAPI::Version.from(version)
+        full_path = self.full_path
+
+        responses = (
+          definitions.common_responses(full_path)&.merge(self.responses) ||
+          self.responses
+        ).reject do |status, response|
+          response.resolve_lazily(definitions).nodoc ||
+            version == OpenAPI::V2_0 && status.is_a?(Status::Range)
+        end
 
         with_openapi_extensions(
           operationId: name,
-          tags: tags.presence,
+          tags:
+            [tags, definitions.common_tags(full_path)]
+              .compact.flatten.uniq.presence,
           summary: summary,
           description: description,
           externalDocs: external_docs&.to_openapi,
-          deprecated: deprecated?.presence,
-          security: security_requirements.map(&:to_openapi).presence
-        ).tap do |result|
-          if version.major == 2
-            if (consumes = consumes(definitions)).present?
-              result[:consumes] = [consumes]
-            end
-            if (produces = produces(definitions)).present?
-              result[:produces] = produces
-            end
-            result[:schemes] = schemes if schemes.present?
-          elsif servers.present?
-            result[:servers] = servers.map do |server|
-              server.to_openapi(version)
-            end
-          end
-          # Parameters (and request body)
-          result[:parameters] = parameters.values.flat_map do |parameter|
-            parameter.to_openapi_parameters(version, definitions)
-          end
-          if request_body
-            if version.major == 2
-              result[:parameters] << request_body.resolve(definitions).to_openapi_parameter
+          **if version == OpenAPI::V2_0
+              resolved_request_body =
+                (request_body || definitions.common_request_body(full_path))
+                &.resolve(definitions)
+              {
+                consumes:
+                  [resolved_request_body&.default_media_range]
+                    .compact.presence,
+                produces:
+                  responses.values.filter_map do |response|
+                    response.resolve(definitions).default_media_type
+                  end.uniq.sort.presence,
+                schemes: schemes.presence,
+                parameters:
+                  begin
+                    params = parameters.values.flat_map do |parameter|
+                      parameter.to_openapi_parameters(version, definitions)
+                    end
+                    if resolved_request_body
+                      params << resolved_request_body.to_openapi_parameter
+                    end
+                    params
+                  end
+              }
             else
-              result[:request_body] = request_body.to_openapi(version)
-            end
-          end
-          # Responses
-          result[:responses] = responses.transform_values do |response|
-            response.to_openapi(version, definitions)
-          end
-          # Callbacks
-          if callbacks.present? && version.major > 2
-            result[:callbacks] = callbacks.transform_values do |callback|
-              callback.to_openapi(version, definitions)
-            end
-          end
-        end
+              {
+                servers:
+                  servers.map do |server|
+                    server.to_openapi(version)
+                  end.presence,
+                callbacks:
+                  callbacks.transform_values do |callback|
+                    callback.to_openapi(version, definitions)
+                  end.presence,
+                parameters:
+                  parameters.values.flat_map do |parameter|
+                    parameter.to_openapi_parameters(version, definitions)
+                  end,
+                request_body: request_body&.to_openapi(version)
+              }
+            end,
+          responses:
+            responses.transform_values do |response|
+              response.to_openapi(version, definitions)
+            end,
+          deprecated: deprecated?.presence,
+          security:
+            [security_requirements, definitions.common_security_requirements(full_path)]
+              .compact.presence&.flatten&.map(&:to_openapi)
+        )
       end
     end
   end

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

@@ -11,12 +11,12 @@ module Jsapi
 
         ##
         # :attr: content_type
-        # The content type used to describe complex parameters in \OpenAPI 3.0 and higher.
-        attribute :content_type, String
+        # The media type used to describe complex parameters in \OpenAPI 3.0 and higher.
+        attribute :content_type, Media::Type
 
         ##
         # :attr: deprecated
-        # Specifies whether or not the parameter is deprecated.
+        # Specifies whether the parameter is marked as deprecated.
         attribute :deprecated, values: [true, false]
 
         ##
@@ -26,7 +26,7 @@ module Jsapi
 
         ##
         # :attr_reader: examples
-        # The examples.
+        # The examples. Maps example names to Example objects or references.
         attribute :examples, { String => Example }, default_key: 'default'
 
         ##
@@ -95,7 +95,8 @@ module Jsapi
             schema.resolve(definitions),
             version,
             location: self.in,
-            content_type: content_type || ('text/plain' if self.in == 'querystring'),
+            content_type: content_type ||
+              (Media::Type::TEXT_PLAIN if self.in == 'querystring'),
             description: description,
             required: required?,
             deprecated: deprecated?,
@@ -191,7 +192,10 @@ module Jsapi
                 }
               else
                 openapi_schema = schema.to_openapi(version).except(:deprecated)
-                openapi_examples = examples&.transform_values(&:to_openapi).presence
+
+                openapi_examples = examples&.transform_values do |example|
+                  example.to_openapi(version)
+                end.presence
                 {
                   deprecated: deprecated.presence,
                   **if content_type.blank?

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Jsapi
+  module Meta
+    module Parameter
+      class Wrapper < Model::Wrapper
+        def schema
+          @schema ||= Schema.wrap(super, definitions)
+        end
+      end
+    end
+  end
+end

data/lib/jsapi/meta/parameter.rb

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

data/lib/jsapi/meta/path.rb

@@ -6,35 +6,72 @@ module Jsapi
     class Path < Model::Base
       ##
       # :attr: description
-      # The description that applies to all operations in this path.
+      # The common description for all operations in this path.
+      #
       # Applies to \OpenAPI 3.0 and higher.
       attribute :description, String
 
+      ##
+      # :attr: model
+      # The model class used by default for all operations in this path.
+      attribute :model, Class
+
       ##
       # :attr_reader: name
       # The relative path as a Pathname.
       attribute :name, Pathname, accessors: %i[reader]
 
+      ##
+      # :attr_reader: owner
+      attribute :owner, accessors: %i[reader]
+
       ##
       # :attr: parameters
-      # The Parameter objects applicable for all operations in this path.
+      # The parameters that apply to all operations in this path. Maps
+      # parameter names to Parameter objects or references.
       attribute :parameters, { String => Parameter }, accessors: %i[reader writer]
 
       ##
-      # :attr_reader: owner
-      attribute :owner, accessors: %i[reader]
+      # :attr: request_body
+      # The RequestBody object or reference used by default by all operations
+      # in this path.
+      attribute :request_body, RequestBody
+
+      ##
+      # :attr: responses
+      # The responses that can be produced by all operations in this path.
+      # Maps instances of Status::Base to Response objects or references.
+      attribute :responses, { Status => Response }, default_key: Status::DEFAULT
+
+      ##
+      # :attr: security_requirements
+      # The security requirements that apply to all operations in this path.
+      #
+      # See SecurityRequirement for further information.
+      attribute :security_requirements, [SecurityRequirement], default: :nil
+
+      alias add_security add_security_requirement
+
+       ##
+      # :attr: servers
+      # The servers that apply by default to all operations in this path.
+      #
+      # Applies to \OpenAPI 3.0 and higher.
+      #
+      # See Server for further information.
+      attribute :servers, [Server]
 
       ##
       # :attr: summary
       # The summary that applies to all operations in this path.
+      #
       # Applies to \OpenAPI 3.0 and higher.
       attribute :summary, String
 
       ##
-      # :attr: servers
-      # The Server objects that applies to all operations in this path.
-      # Applies to \OpenAPI 3.0 and higher.
-      attribute :servers, [Server]
+      # :attr: tags
+      # The tags that apply to all operations in this path.
+      attribute :tags, [String]
 
       # Creates a new path with the given name and owner.
       def initialize(name, owner, keywords = {})
@@ -44,13 +81,22 @@ module Jsapi
       end
 
       def add_parameter(name, keywords = {}) # :nodoc:
-        name = name.to_s
-
-        Parameter.new(name, keywords).tap do |parameter|
-          (@parameters ||= {})[name] = parameter
-          @owner.try(:invalidate_path_parameters, self.name)
+        try_modify_attribute!(:parameters) do
+          name = name.to_s
+          (@parameters ||= {})[name] = Parameter.new(name, keywords)
         end
       end
+
+      def inspect(*attributes) # :nodoc:
+        super(*(attributes.presence || self.class.attribute_names).without(:owner))
+      end
+
+      protected
+
+      def attribute_changed(name)
+        @owner.try(:invalidate_path_attribute, self.name, name)
+        super
+      end
     end
   end
 end

data/lib/jsapi/meta/pathname.rb

@@ -5,10 +5,11 @@ module Jsapi
     # Represents a relative path name.
     class Pathname
       class << self
-        # Creates a Pathname from +name+.
+        # Transforms +name+ to an instance of this class.
         def from(name)
           return name if name.is_a?(Pathname)
 
+          name = name[1..].presence if name&.match?(%r{\A/+\z})
           name.nil? ? new : new(name)
         end
       end
@@ -30,8 +31,8 @@ module Jsapi
 
       alias eql? ==
 
-      # Creates a new Pathname by appending +other+ to +self+.
-      # Returns +self+ if +other+ is nil.
+      # Creates a new Pathname by appending +other+ to itself.
+      # Returns itself if +other+ is nil.
       def +(other)
         return self if other.nil?
 
@@ -55,6 +56,8 @@ module Jsapi
           index.zero? && segment.blank? ? '//' : "/#{segment}"
         end&.join || '/'
       end
+
+      alias as_json to_s
     end
   end
 end

data/lib/jsapi/meta/property.rb

@@ -4,6 +4,16 @@ module Jsapi
   module Meta
     # Specifies a property
     class Property < Model::Base
+      class Wrapper < Model::Wrapper
+        delegate :additional_properties, :default_value, :items, to: :schema
+
+        def schema
+          @schema ||= Schema.wrap(super, definitions)
+        end
+      end
+
+      include Model::Wrappable
+
       delegate_missing_to :schema
 
       ##