scorpio 0.4.5 → 0.6.0

data/lib/scorpio/openapi/operation.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Scorpio
   module OpenAPI
     # An OpenAPI operation
@@ -43,37 +45,42 @@ module Scorpio
       end
       include Configurables
 
-      # @return [Boolean] v3?
+      # openapi v3?
+      # @return [Boolean]
       def v3?
         is_a?(V3::Operation)
       end
 
-      # @return [Boolean] v2?
+      # openapi v2?
+      # @return [Boolean]
       def v2?
         is_a?(V2::Operation)
       end
 
-      # @return [Scorpio::OpenAPI::Document] the document whence this operation came
+      # the document whence this operation came
+      # @return [Scorpio::OpenAPI::Document]
       def openapi_document
-        parent_jsis.detect { |p| p.is_a?(Scorpio::OpenAPI::Document) }
+        jsi_parent_nodes.detect { |p| p.is_a?(Scorpio::OpenAPI::Document) }
       end
 
+      # @return [String]
       def path_template_str
         return @path_template_str if instance_variable_defined?(:@path_template_str)
-        raise(Bug) unless parent_jsi.is_a?(Scorpio::OpenAPI::V2::PathItem) || parent_jsi.is_a?(Scorpio::OpenAPI::V3::PathItem)
-        raise(Bug) unless parent_jsi.parent_jsi.is_a?(Scorpio::OpenAPI::V2::Paths) || parent_jsi.parent_jsi.is_a?(Scorpio::OpenAPI::V3::Paths)
-        @path_template_str = parent_jsi.jsi_ptr.reference_tokens.last
+        raise(Bug) unless jsi_parent_node.is_a?(Scorpio::OpenAPI::V2::PathItem) || jsi_parent_node.is_a?(Scorpio::OpenAPI::V3::PathItem)
+        raise(Bug) unless jsi_parent_node.jsi_parent_node.is_a?(Scorpio::OpenAPI::V2::Paths) || jsi_parent_node.jsi_parent_node.is_a?(Scorpio::OpenAPI::V3::Paths)
+        @path_template_str = jsi_parent_node.jsi_ptr.tokens.last
       end
 
-      # @return [Addressable::Template] the path as an Addressable::Template
+      # the path as an Addressable::Template
+      # @return [Addressable::Template]
       def path_template
         return @path_template if instance_variable_defined?(:@path_template)
         @path_template = Addressable::Template.new(path_template_str)
       end
 
+      # the URI template, consisting of the base_url concatenated with the path template
       # @param base_url [#to_str] the base URL to which the path template is appended
-      # @return [Addressable::Template] the URI template, consisting of the base_url
-      #   concatenated with the path template
+      # @return [Addressable::Template]
       def uri_template(base_url: self.base_url)
         unless base_url
           raise(ArgumentError, "no base_url has been specified for operation #{self}")
@@ -83,33 +90,38 @@ module Scorpio
         Addressable::Template.new(File.join(base_url, path_template_str))
       end
 
-      # @return the HTTP method of this operation as indicated by the attribute name
-      #   for this operation from the parent PathItem
+      # the HTTP method of this operation as indicated by the attribute name for this operation
+      # from the parent PathItem
+      # @return [String]
       def http_method
         return @http_method if instance_variable_defined?(:@http_method)
-        raise(Bug) unless parent_jsi.is_a?(Scorpio::OpenAPI::V2::PathItem) || parent_jsi.is_a?(Scorpio::OpenAPI::V3::PathItem)
-        @http_method = jsi_ptr.reference_tokens.last
+        raise(Bug) unless jsi_parent_node.is_a?(Scorpio::OpenAPI::V2::PathItem) || jsi_parent_node.is_a?(Scorpio::OpenAPI::V3::PathItem)
+        @http_method = jsi_ptr.tokens.last
       end
 
-      # @return [String] a short identifier for this operation appropriate for an error message
+      # a short identifier for this operation appropriate for an error message
+      # @return [String]
       def human_id
         operationId || "path: #{path_template_str}, method: #{http_method}"
       end
 
+      # @param status [String, Integer]
       # @return [Scorpio::OpenAPI::V3::Response, Scorpio::OpenAPI::V2::Response]
       def oa_response(status: )
         status = status.to_s if status.is_a?(Numeric)
-        if self.responses
-          _, oa_response = self.responses.detect { |k, v| k.to_s == status }
-          oa_response ||= self.responses['default']
+        if responses
+          _, oa_response = responses.detect { |k, v| k.to_s == status }
+          oa_response ||= responses['default']
         end
         oa_response
       end
 
+      # the parameters specified for this operation, plus any others scorpio considers to be parameters.
+      #
       # this method is not intended to be API-stable at the moment.
       #
-      # @return [#to_ary<#to_h>] the parameters specified for this operation, plus any others
-      #   scorpio considers to be parameters
+      # @api private
+      # @return [#to_ary<#to_h>]
       def inferred_parameters
         parameters = self.parameters ? self.parameters.to_a.dup : []
         path_template.variables.each do |var|
@@ -127,7 +139,8 @@ module Scorpio
         parameters
       end
 
-      # @return [Module] a module with accessor methods for unambiguously named parameters of this operation.
+      # a module with accessor methods for unambiguously named parameters of this operation.
+      # @return [Module]
       def request_accessor_module
         return @request_accessor_module if instance_variable_defined?(:@request_accessor_module)
         @request_accessor_module = begin
@@ -136,7 +149,7 @@ module Scorpio
             instance_method_modules = [Request, Request::Configurables]
             instance_method_names = instance_method_modules.map do |mod|
               (mod.instance_methods + mod.private_instance_methods).map(&:to_s)
-            end.inject(Set.new, &:|)
+            end.inject(Set.new, &:merge)
             params_by_name.each do |name, params|
               next if instance_method_names.include?(name)
               if params.size == 1
@@ -149,19 +162,22 @@ module Scorpio
         end
       end
 
-      # @param a, b are passed to Scorpio::Request#initialize
+      # instantiates a {Scorpio::Request} for this operation.
+      # parameters are all passed to {Scorpio::Request#initialize}.
       # @return [Scorpio::Request]
       def build_request(*a, &b)
         Scorpio::Request.new(self, *a, &b)
       end
 
-      # @param a, b are passed to Scorpio::Request#initialize
+      # runs a {Scorpio::Request} for this operation, returning a {Scorpio::Ur}.
+      # parameters are all passed to {Scorpio::Request#initialize}.
       # @return [Scorpio::Ur] response ur
       def run_ur(*a, &b)
         build_request(*a, &b).run_ur
       end
 
-      # @param a, b are passed to Scorpio::Request#initialize
+      # runs a {Scorpio::Request} for this operation - see {Scorpio::Request#run}.
+      # parameters are all passed to {Scorpio::Request#initialize}.
       # @return response body object
       def run(*a, &b)
         build_request(*a, &b).run
@@ -174,7 +190,7 @@ module Scorpio
       # Describes a single API operation on a path.
       #
       # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#operationObject
-      class Operation
+      module Operation
         module Configurables
           def scheme
             # not applicable; for OpenAPI v3, scheme is specified by servers.
@@ -212,17 +228,19 @@ module Scorpio
             requestBody['content'] &&
             requestBody['content'][media_type] &&
             requestBody['content'][media_type]['schema']
-          schema_object ? JSI::Schema.from_object(schema_object) : nil
+          schema_object ? JSI::Schema.ensure_schema(schema_object) : nil
         end
 
-        # @return [Array<JSI::Schema>]
+        # @return [JSI::SchemaSet]
         def request_schemas
-          if requestBody && requestBody['content']
-            # oamt is for Scorpio::OpenAPI::V3::MediaType
-            oamts = requestBody['content'].values.select { |oamt| oamt.key?('schema') }
-            oamts.map { |oamt| JSI::Schema.from_object(oamt['schema']) }
-          else
-            []
+          JSI::SchemaSet.build do |schemas|
+            if requestBody && requestBody['content']
+              requestBody['content'].each_value do |oa_media_type|
+                if oa_media_type['schema']
+                  schemas << oa_media_type['schema']
+                end
+              end
+            end
           end
         end
 
@@ -232,13 +250,30 @@ module Scorpio
           oa_media_types = oa_response ? oa_response['content'] : nil # Scorpio::OpenAPI::V3::MediaTypes
           oa_media_type = oa_media_types ? oa_media_types[media_type] : nil # Scorpio::OpenAPI::V3::MediaType
           oa_schema = oa_media_type ? oa_media_type['schema'] : nil # Scorpio::OpenAPI::V3::Schema
-          oa_schema ? JSI::Schema.new(oa_schema) : nil
+          oa_schema ? JSI::Schema.ensure_schema(oa_schema) : nil
+        end
+
+        # @return [JSI::SchemaSet]
+        def response_schemas
+          JSI::SchemaSet.build do |schemas|
+            if responses
+              responses.each_value do |oa_response|
+                if oa_response['content']
+                  oa_response['content'].each_value do |oa_media_type|
+                    if oa_media_type['schema']
+                      schemas << oa_media_type['schema']
+                    end
+                  end
+                end
+              end
+            end
+          end
         end
       end
     end
     module V2
       raise(Bug, 'const_defined? Scorpio::OpenAPI::V2::Operation') unless const_defined?(:Operation)
-      class Operation
+      module Operation
         module Configurables
           attr_writer :scheme
           def scheme
@@ -264,7 +299,8 @@ module Scorpio
         end
         include Configurables
 
-        # @return [#to_hash] the body parameter
+        # the body parameter
+        # @return [#to_hash]
         # @raise [Scorpio::OpenAPI::SemanticError] if there's more than one body param
         def body_parameter
           body_parameters = (parameters || []).select { |parameter| parameter['in'] == 'body' }
@@ -278,19 +314,20 @@ module Scorpio
           end
         end
 
+        # request schema for the given media_type
         # @param media_type unused
-        # @return [JSI::Schema] request schema for the given media_type
+        # @return [JSI::Schema]
         def request_schema(media_type: nil)
           if body_parameter && body_parameter['schema']
-            JSI::Schema.new(body_parameter['schema'])
+            JSI::Schema.ensure_schema(body_parameter['schema'])
           else
             nil
           end
         end
 
-        # @return [Array<JSI::Schema>]
+        # @return [JSI::SchemaSet]
         def request_schemas
-          request_schema ? [request_schema] : []
+          request_schema ? JSI::SchemaSet[request_schema] : JSI::SchemaSet[]
         end
 
         # @param status [Integer, String] response status
@@ -299,7 +336,20 @@ module Scorpio
         def response_schema(status: , media_type: nil)
           oa_response = self.oa_response(status: status)
           oa_response_schema = oa_response ? oa_response['schema'] : nil # Scorpio::OpenAPI::V2::Schema
-          oa_response_schema ? JSI::Schema.new(oa_response_schema) : nil
+          oa_response_schema ? JSI::Schema.ensure_schema(oa_response_schema) : nil
+        end
+
+        # @return [JSI::SchemaSet]
+        def response_schemas
+          JSI::SchemaSet.build do |schemas|
+            if responses
+              responses.each_value do |oa_response|
+                if oa_response['schema']
+                  schemas << oa_response['schema']
+                end
+              end
+            end
+          end
         end
       end
     end

data/lib/scorpio/openapi/operations_scope.rb

@@ -1,13 +1,20 @@
+# frozen_string_literal: true
+
 module Scorpio
   module OpenAPI
     # OperationsScope acts as an Enumerable of the Operations for an openapi_document,
     # and offers subscripting by operationId.
     class OperationsScope
-      include JSI::Memoize
-
       # @param openapi_document [Scorpio::OpenAPI::Document]
       def initialize(openapi_document)
         @openapi_document = openapi_document
+        @operations_by_id = Hash.new do |h, operationId|
+          op = detect { |operation| operation.operationId == operationId }
+          unless op
+            raise(::KeyError, "operationId not found: #{operationId.inspect}")
+          end
+          h[operationId] = op
+        end
       end
       attr_reader :openapi_document
 
@@ -23,17 +30,12 @@ module Scorpio
       end
       include Enumerable
 
-      # @param operationId
-      # @return [Scorpio::OpenAPI::Operation] the operation with the given operationId
+      # finds an operation with the given `operationId`
+      # @param operationId [String] the operationId of the operation to find
+      # @return [Scorpio::OpenAPI::Operation]
       # @raise [::KeyError] if the given operationId does not exist
       def [](operationId)
-        memoize(:[], operationId) do |operationId_|
-          detect { |operation| operation.operationId == operationId_ }.tap do |op|
-            unless op
-              raise(::KeyError, "operationId not found: #{operationId_.inspect}")
-            end
-          end
-        end
+        @operations_by_id[operationId]
       end
     end
   end

data/lib/scorpio/openapi/reference.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Scorpio
+  module OpenAPI
+    module Reference
+      # overrides JSI::Base#[] to implicitly dereference this Reference, except when
+      # the given token is present in this Reference's instance (this should usually
+      # only apply to the token '$ref')
+      def [](token, *a, &b)
+        if respond_to?(:to_hash) && !key?(token)
+          deref do |deref_jsi|
+            return deref_jsi[token]
+          end
+        end
+        return super
+      end
+
+      # yields or returns the target of this reference
+      # @yield [JSI::Base] if a block is given
+      # @return [JSI::Base]
+      def deref
+        return unless respond_to?(:to_hash) && self['$ref'].respond_to?(:to_str)
+
+        ref_uri = Addressable::URI.parse(self['$ref'])
+        ref_uri_nofrag = ref_uri.merge(fragment: nil)
+
+        if !ref_uri_nofrag.empty? || ref_uri.fragment.nil?
+          raise(NotImplementedError,
+            "Scorpio currently only supports fragment URIs as OpenAPI references. cannot find reference by uri: #{self['$ref']}"
+          )
+        end
+
+        ptr = JSI::Ptr.from_fragment(ref_uri.fragment)
+        deref_jsi = ptr.evaluate(jsi_root_node)
+
+        # TODO type check deref_jsi
+
+        yield deref_jsi if block_given?
+
+        deref_jsi
+      end
+    end
+  end
+end

data/lib/scorpio/openapi/tag.rb

@@ -0,0 +1,15 @@
+module Scorpio
+  module OpenAPI
+    module Tag
+      # operations in the openapi document which have a tag with this tag's name
+      # @return [Enumerable<Scorpio::OpenAPI::Operation>]
+      def operations
+        unless jsi_root_node.is_a?(OpenAPI::Document)
+          raise("Tag#operations cannot be used on a Tag that is not inside an OpenAPI document")
+        end
+
+        jsi_root_node.operations.select { |op| op.tags.respond_to?(:to_ary) && op.tags.include?(name) }
+      end
+    end
+  end
+end

data/lib/scorpio/openapi/v3/server.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Scorpio
   module OpenAPI
     module V3
@@ -6,7 +8,7 @@ module Scorpio
       # An object representing a Server.
       #
       # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#serverObject
-      class Server
+      module Server
         # expands this server's #url using the given_server_variables. any variables
         # that are in the url but not in the given server variables are filled in
         # using the default value for the variable.
@@ -34,7 +36,7 @@ module Scorpio
             server_variables = given_server_variables
           end
           template = Addressable::Template.new(url)
-          template.expand(server_variables)
+          template.expand(server_variables).freeze
         end
       end
     end