scorpio 0.5.0 → 0.6.0

data/lib/scorpio/openapi.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Scorpio
   module OpenAPI
     class Error < StandardError
@@ -15,15 +17,37 @@ module Scorpio
     autoload :Operation, 'scorpio/openapi/operation'
     autoload :Document, 'scorpio/openapi/document'
     autoload :Reference, 'scorpio/openapi/reference'
+    autoload :Tag, 'scorpio/openapi/tag'
     autoload :OperationsScope, 'scorpio/openapi/operations_scope'
 
     module V3
-      openapi_schema = JSI::Schema.new(::YAML.load_file(Scorpio.root.join('documents/github.com/OAI/OpenAPI-Specification/blob/oas3-schema/schemas/v3.0/schema.yaml')))
+      openapi_document_schema = JSI::JSONSchemaOrgDraft04.new_schema(::YAML.load_file(Scorpio.root.join(
+        'documents/github.com/OAI/OpenAPI-Specification/blob/oas3-schema/schemas/v3.0/schema.yaml'
+      )))
+
+      # the schema represented by Scorpio::OpenAPI::V3::Schema will describe schemas itself, so we set it
+      # include on its schema module the jsi_schema_instance_modules that implement schema functionality.
+      describe_schema = [
+        openapi_document_schema.definitions['Schema'],
+        openapi_document_schema.definitions['SchemaReference'],
+        # instead of the Schema definition allowing boolean, properties['additionalProperties']
+        # is a oneOf which allows a Schema, SchemaReference, or boolean.
+        # instances of the former two already include the schema implementation (per the previous
+        # describes_schema entries), but the boolean does not.
+        # including in properties['additionalProperties'] applies to any additionalProperties.
+        # (including in properties['additionalProperties'].anyOf[2] would extend booleans too, without
+        # the redundant inclusion that results for Schema and SchemaRef, but redundant inclusion is not
+        # a problem, and this way also applies when none of the anyOf match due to schema errors.)
+        openapi_document_schema.definitions['Schema'].properties['additionalProperties'],
+      ]
+      describe_schema.each { |s| s.jsi_schema_instance_modules = [JSI::Schema::Draft04] }
 
-      Document = openapi_schema.jsi_schema_module
+      Document = openapi_document_schema.jsi_schema_module
 
       # naming these is not strictly necessary, but is nice to have.
-      # generated: `puts JSI::Schema.new(::YAML.load_file(Scorpio.root.join('documents/github.com/OAI/OpenAPI-Specification/blob/oas3-schema/schemas/v3.0/schema.yaml')))['definitions'].select { |k,v| ['object', nil].include?(v['type']) }.keys.map { |k| "#{k[0].upcase}#{k[1..-1]} = Document.definitions['#{k}']" }`
+      # generated: `puts Scorpio::OpenAPI::V3::Document.schema.definitions.select { |k,v| ['object', nil].include?(v['type']) }.keys.map { |k| "#{k[0].upcase}#{k[1..-1]} = Document.definitions['#{k}']" }`
+
+
       Reference      = Document.definitions['Reference']
       SchemaReference = Document.definitions['SchemaReference']
       Info           = Document.definitions['Info']
@@ -86,18 +110,29 @@ module Scorpio
       Callback               = Document.definitions['Callback']
       Encoding              = Document.definitions['Encoding']
 
-      # the schema of Scorpio::OpenAPI::V3::Schema describes a schema itself, so we extend it
-      # with the module indicating that.
-      Schema.schema.extend(JSI::Schema::DescribesSchema)
-      SchemaReference.schema.extend(JSI::Schema::DescribesSchema)
+      raise(Bug) unless Schema < JSI::Schema
+      raise(Bug) unless SchemaReference < JSI::Schema
     end
     module V2
-      openapi_schema = JSI::Schema.new(::JSON.parse(Scorpio.root.join('documents/swagger.io/v2/schema.json').read))
+      openapi_document_schema = JSI.new_schema(::JSON.parse(Scorpio.root.join(
+        'documents/swagger.io/v2/schema.json'
+      ).read))
+
+      # the schema represented by Scorpio::OpenAPI::V2::Schema will describe schemas itself, so we set it to
+      # include on its schema module the jsi_schema_instance_modules that implement schema functionality.
+      describe_schema = [
+        openapi_document_schema.definitions['schema'],
+        # comments above on v3's definitions['Schema'].properties['additionalProperties'] apply here too
+        openapi_document_schema.definitions['schema'].properties['additionalProperties'],
+      ]
+      describe_schema.each { |s| s.jsi_schema_instance_modules = [JSI::Schema::Draft04] }
 
-      Document = openapi_schema.jsi_schema_module
+      Document = openapi_document_schema.jsi_schema_module
 
       # naming these is not strictly necessary, but is nice to have.
-      # generated: `puts JSI::Schema.new(::JSON.parse(Scorpio.root.join('documents/swagger.io/v2/schema.json').read))['definitions'].select { |k,v| ['object', nil].include?(v['type']) }.keys.map { |k| "#{k[0].upcase}#{k[1..-1]} = Document.definitions['#{k}']" }`
+      # generated: `puts Scorpio::OpenAPI::V2::Document.schema.definitions.select { |k,v| ['object', nil].include?(v['type']) }.keys.map { |k| "#{k[0].upcase}#{k[1..-1]} = Document.definitions['#{k}']" }`
+
+
       Info            = Document.definitions['info']
       Contact          = Document.definitions['contact']
       License           = Document.definitions['license']
@@ -153,15 +188,12 @@ module Scorpio
       Enum         = Document.definitions['enum']
       JsonReference = Document.definitions['jsonReference']
 
-      # the schema of Scorpio::OpenAPI::V2::Schema describes a schema itself, so we extend it
-      # with the module indicating that.
-      Schema.schema.extend(JSI::Schema::DescribesSchema)
+      raise(Bug) unless Schema < JSI::Schema
     end
 
-    begin
-      # the autoloads for OpenAPI::Operation and OpenAPI::Document
-      # should not be triggered until all the classes their files reference are defined (above)
-    end # (this block is here just so the above informative comment is not interpreted as module doc)
+    # the autoloads for OpenAPI::Operation and OpenAPI::Document are triggered below. these
+    # should not be triggered until all the classes their files reference are defined (above).
+
 
     module V3
       module Operation
@@ -173,6 +205,9 @@ module Scorpio
       module Reference
         include OpenAPI::Reference
       end
+      module Tag
+        include OpenAPI::Tag
+      end
       require 'scorpio/openapi/v3/server'
     end
 
@@ -186,6 +221,9 @@ module Scorpio
       module JsonReference
         include OpenAPI::Reference
       end
+      module Tag
+        include OpenAPI::Tag
+      end
     end
   end
 end

data/lib/scorpio/pickle_adapter.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'scorpio'
 require 'pickle'
 

data/lib/scorpio/request.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module Scorpio
   class Request
-    SUPPORTED_REQUEST_MEDIA_TYPES = ['application/json', 'application/x-www-form-urlencoded']
-    FALLBACK_CONTENT_TYPE = 'application/x-www-form-urlencoded'
+    SUPPORTED_REQUEST_MEDIA_TYPES = ['application/json'.freeze, 'application/x-www-form-urlencoded'.freeze].freeze
+    FALLBACK_CONTENT_TYPE = 'application/x-www-form-urlencoded'.freeze
 
     def self.best_media_type(media_types)
       if media_types.size == 1
@@ -118,12 +120,12 @@ module Scorpio
     def initialize(operation, configuration = {}, &b)
       @operation = operation
 
-      configuration = JSI.stringify_symbol_keys(configuration)
+      configuration = JSI::Util.stringify_symbol_keys(configuration)
       params_set = Set.new # the set of params that have been set
       # do the Configurables first
       configuration.each do |name, value|
         if Configurables.public_method_defined?("#{name}=")
-          Configurables.instance_method("#{name}=").bind(self).call(value)
+          Configurables.instance_method("#{name}=").bind_call(self, value)
           params_set << name
         end
       end
@@ -148,21 +150,23 @@ module Scorpio
       operation.openapi_document
     end
 
-    # @return [Symbol] the http method for this request - :get, :post, etc.
+    # the http method for this request
+    # @return [String]
     def http_method
-      operation.http_method.downcase.to_sym
+      operation.http_method
     end
 
-    # @return [Addressable::Template] the template for the request's path, to be expanded
-    #   with path_params and appended to the request's base_url
+    # the template for the request's path, to be expanded with {Configurables#path_params} and appended to
+    # the request's {Configurables#base_url}
+    # @return [Addressable::Template]
     def path_template
       operation.path_template
     end
 
-    # @return [Addressable::URI] an Addressable::URI containing only the path to append to
-    #   the base_url for this request
+    # an Addressable::URI containing only the path to append to the {Configurables#base_url} for this request
+    # @return [Addressable::URI]
     def path
-      path_params = JSI.stringify_symbol_keys(self.path_params)
+      path_params = JSI::Util.stringify_symbol_keys(self.path_params)
       missing_variables = path_template.variables - path_params.keys
       if missing_variables.any?
         raise(ArgumentError, "path #{operation.path_template_str} for operation #{operation.human_id} requires path_params " +
@@ -174,24 +178,26 @@ module Scorpio
           "which were empty: #{empty_variables.inspect}")
       end
 
-      path_template.expand(path_params).tap do |path|
-        if query_params
-          path.query_values = query_params
-        end
+      path = path_template.expand(path_params)
+      if query_params
+        path.query_values = query_params
       end
+      path.freeze
     end
 
-    # @return [Addressable::URI] the full URL for this request
+    # the full URL for this request
+    # @return [Addressable::URI]
     def url
       unless base_url
         raise(ArgumentError, "no base_url has been specified for request")
       end
       # we do not use Addressable::URI#join as the paths should just be concatenated, not resolved.
       # we use File.join just to deal with consecutive slashes.
-      Addressable::URI.parse(File.join(base_url, path))
+      Addressable::URI.parse(File.join(base_url, path)).freeze
     end
 
-    # @return [::Ur::ContentType] the value of the request Content-Type header
+    # the value of the request Content-Type header
+    # @return [::Ur::ContentType]
     def content_type_header
       headers.each do |k, v|
         return ::Ur::ContentType.new(v) if k =~ /\Acontent[-_]type\z/i
@@ -199,8 +205,9 @@ module Scorpio
       nil
     end
 
-    # @return [::Ur::ContentType] Content-Type for this request, taken from request headers if
-    #   present, or the request media_type.
+    # Content-Type for this request, taken from request headers if present, or the
+    # request {Configurables#media_type}.
+    # @return [::Ur::ContentType]
     def content_type
       content_type_header || (media_type ? ::Ur::ContentType.new(media_type) : nil)
     end
@@ -232,16 +239,17 @@ module Scorpio
     # @param name [String, Symbol] the 'name' property of one applicable parameter
     # @param value [Object] the applicable parameter will be applied to the request with the given value.
     # @return [Object] echoes the value param
-    # @raise [Scorpio::AmbiguousParameter] if more than one parameter has the given name
+    # @raise (see #param_for!)
     def set_param(name, value)
       param = param_for!(name)
       set_param_from(param['in'], param['name'], value)
       value
     end
 
+    # returns the value of the named parameter on this request
     # @param name [String, Symbol] the 'name' property of one applicable parameter
-    # @return [Object] the value of the named parameter on this request
-    # @raise [Scorpio::AmbiguousParameter] if more than one parameter has the given name
+    # @return [Object]
+    # @raise (see #param_for!)
     def get_param(name)
       param = param_for!(name)
       get_param_from(param['in'], param['name'])
@@ -249,6 +257,7 @@ module Scorpio
 
     # @param name [String, Symbol] the 'name' property of one applicable parameter
     # @return [#to_hash, nil]
+    # @raise [Scorpio::AmbiguousParameter] if more than one parameter has the given name
     def param_for(name)
       name = name.to_s if name.is_a?(Symbol)
       params = operation.inferred_parameters.select { |p| p['name'] == name }
@@ -263,17 +272,21 @@ module Scorpio
       end
     end
 
-    # @param name [String, Symbol] the name or {in}.{name} (e.g. "query.search") for the applicable parameter.
+    # @param name [String, Symbol] the 'name' property of one applicable parameter
     # @return [#to_hash]
+    # @raise [Scorpio::ParameterError] if no parameter has the given name
+    # @raise (see #param_for)
     def param_for!(name)
       param_for(name) || raise(ParameterError, "There is no parameter named #{name} on operation #{operation.human_id}:\n#{operation.pretty_inspect.chomp}")
     end
 
-    # @param in [String, Symbol] one of 'path', 'query', 'header', or 'cookie' - where to apply the named value
+    # applies the named value to the appropriate parameter of the request
+    # @param param_in [String, Symbol] one of 'path', 'query', 'header', or 'cookie' - where to apply
+    #   the named value
     # @param name [String, Symbol] the parameter name to apply the value to
     # @param value [Object] the value
     # @return [Object] echoes the value param
-    # @raise [ArgumentError] invalid 'in' parameter
+    # @raise [ArgumentError] invalid `param_in` parameter
     # @raise [NotImplementedError] cookies aren't implemented
     def set_param_from(param_in, name, value)
       param_in = param_in.to_s if param_in.is_a?(Symbol)
@@ -292,10 +305,12 @@ module Scorpio
       value
     end
 
-    # @param in [String, Symbol] one of 'path', 'query', 'header', or 'cookie' - where to apply the named value
+    # returns the value of the named parameter from the specified `param_in` on this request
+    # @param param_in [String, Symbol] one of 'path', 'query', 'header', or 'cookie' - where to retrieve
+    #   the named value
     # @param name [String, Symbol] the parameter name
-    # @return [Object] the value of the named parameter on this request
-    # @raise [ArgumentError] invalid 'in' parameter
+    # @return [Object]
+    # @raise [ArgumentError] invalid `param_in` parameter
     # @raise [NotImplementedError] cookies aren't implemented
     def get_param_from(param_in, name)
       if param_in == 'path'
@@ -333,17 +348,17 @@ module Scorpio
         headers.update(self.headers)
       end
       ur = nil
-      faraday_connection(-> (yur) { ur = yur }).run_request(http_method, url, body, headers)
+      faraday_connection(-> (yur) { ur = yur }).run_request(http_method.downcase.to_sym, url, body, headers)
       ur.scorpio_request = self
       ur
     end
 
     # runs this request. returns the response body object - that is, the response body
     # parsed according to an understood media type, and instantiated with the applicable
-    # response schema if one is specified. see Scorpio::Response#body_object for more detail.
+    # response schema if one is specified. see {Scorpio::Response#body_object} for more detail.
     #
     # @raise [Scorpio::HTTPError] if the request returns a 4xx or 5xx status, the appropriate
-    #   error is raised - see Scorpio::HTTPErrors
+    #   error is raised - see {Scorpio::HTTPErrors}
     def run
       ur = run_ur
       ur.raise_on_http_error