scorpio 0.4.5 → 0.6.0

data/lib/scorpio/openapi.rb

@@ -1,5 +1,9 @@
+# frozen_string_literal: true
+
 module Scorpio
   module OpenAPI
+    class Error < StandardError
+    end
     # an error in the semantics of an openapi document. for example, an Operation with
     # two body parameters (in v2, not possible in v3) is a SemanticError. an Operation
     # with more than one parameter with the same 'name' and 'in' properties would also be
@@ -7,172 +11,219 @@ module Scorpio
     #
     # an instance of a SemanticError may or may not correspond to a validation error of
     # an OpenAPI document against the OpenAPI schema.
-    class SemanticError
+    class SemanticError < Error
     end
 
     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_class = proc do |*key|
-        JSI.class_for_schema(key.inject(openapi_schema, &:[]))
-      end
+      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'
+      )))
 
-      Document = openapi_class.call()
+      # 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_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]} = openapi_class.call('definitions', '#{k}')" }`
-      Reference  = openapi_class.call('definitions', 'Reference')
-      Info        = openapi_class.call('definitions', 'Info')
-      Contact      = openapi_class.call('definitions', 'Contact')
-      License       = openapi_class.call('definitions', 'License')
-      Server         = openapi_class.call('definitions', 'Server')
-      ServerVariable  = openapi_class.call('definitions', 'ServerVariable')
-      Components       = openapi_class.call('definitions', 'Components')
-      Schema            = openapi_class.call('definitions', 'Schema')
-      Discriminator      = openapi_class.call('definitions', 'Discriminator')
-      XML                 = openapi_class.call('definitions', 'XML')
-      Response             = openapi_class.call('definitions', 'Response')
-      MediaType             = openapi_class.call('definitions', 'MediaType')
-      MediaTypeWithExample   = openapi_class.call('definitions', 'MediaTypeWithExample')
-      MediaTypeWithExamples   = openapi_class.call('definitions', 'MediaTypeWithExamples')
-      Example                  = openapi_class.call('definitions', 'Example')
-      Header                    = openapi_class.call('definitions', 'Header')
-      HeaderWithSchema           = openapi_class.call('definitions', 'HeaderWithSchema')
-      HeaderWithSchemaWithExample = openapi_class.call('definitions', 'HeaderWithSchemaWithExample')
-      HeaderWithSchemaWithExamples = openapi_class.call('definitions', 'HeaderWithSchemaWithExamples')
-      HeaderWithContent           = openapi_class.call('definitions', 'HeaderWithContent')
-      Paths                      = openapi_class.call('definitions', 'Paths')
-      PathItem                    = openapi_class.call('definitions', 'PathItem')
-      Operation                    = openapi_class.call('definitions', 'Operation')
-      Responses                     = openapi_class.call('definitions', 'Responses')
-      SecurityRequirement            = openapi_class.call('definitions', 'SecurityRequirement')
-      Tag                             = openapi_class.call('definitions', 'Tag')
-      ExternalDocumentation            = openapi_class.call('definitions', 'ExternalDocumentation')
-      Parameter                         = openapi_class.call('definitions', 'Parameter')
-      ParameterWithSchema                = openapi_class.call('definitions', 'ParameterWithSchema')
-      ParameterWithSchemaWithExample      = openapi_class.call('definitions', 'ParameterWithSchemaWithExample')
-      ParameterWithSchemaWithExampleInPath = openapi_class.call('definitions', 'ParameterWithSchemaWithExampleInPath')
-      ParameterWithSchemaWithExampleInQuery = openapi_class.call('definitions', 'ParameterWithSchemaWithExampleInQuery')
-      ParameterWithSchemaWithExampleInHeader = openapi_class.call('definitions', 'ParameterWithSchemaWithExampleInHeader')
-      ParameterWithSchemaWithExampleInCookie = openapi_class.call('definitions', 'ParameterWithSchemaWithExampleInCookie')
-      ParameterWithSchemaWithExamples       = openapi_class.call('definitions', 'ParameterWithSchemaWithExamples')
-      ParameterWithSchemaWithExamplesInPath = openapi_class.call('definitions', 'ParameterWithSchemaWithExamplesInPath')
-      ParameterWithSchemaWithExamplesInQuery = openapi_class.call('definitions', 'ParameterWithSchemaWithExamplesInQuery')
-      ParameterWithSchemaWithExamplesInHeader = openapi_class.call('definitions', 'ParameterWithSchemaWithExamplesInHeader')
-      ParameterWithSchemaWithExamplesInCookie = openapi_class.call('definitions', 'ParameterWithSchemaWithExamplesInCookie')
-      ParameterWithContent                   = openapi_class.call('definitions', 'ParameterWithContent')
-      ParameterWithContentInPath            = openapi_class.call('definitions', 'ParameterWithContentInPath')
-      ParameterWithContentNotInPath        = openapi_class.call('definitions', 'ParameterWithContentNotInPath')
-      RequestBody                         = openapi_class.call('definitions', 'RequestBody')
-      SecurityScheme                     = openapi_class.call('definitions', 'SecurityScheme')
-      APIKeySecurityScheme              = openapi_class.call('definitions', 'APIKeySecurityScheme')
-      HTTPSecurityScheme               = openapi_class.call('definitions', 'HTTPSecurityScheme')
-      NonBearerHTTPSecurityScheme     = openapi_class.call('definitions', 'NonBearerHTTPSecurityScheme')
-      BearerHTTPSecurityScheme       = openapi_class.call('definitions', 'BearerHTTPSecurityScheme')
-      OAuth2SecurityScheme          = openapi_class.call('definitions', 'OAuth2SecurityScheme')
-      OpenIdConnectSecurityScheme  = openapi_class.call('definitions', 'OpenIdConnectSecurityScheme')
-      OAuthFlows                  = openapi_class.call('definitions', 'OAuthFlows')
-      ImplicitOAuthFlow          = openapi_class.call('definitions', 'ImplicitOAuthFlow')
-      PasswordOAuthFlow         = openapi_class.call('definitions', 'PasswordOAuthFlow')
-      ClientCredentialsFlow     = openapi_class.call('definitions', 'ClientCredentialsFlow')
-      AuthorizationCodeOAuthFlow = openapi_class.call('definitions', 'AuthorizationCodeOAuthFlow')
-      Link                      = openapi_class.call('definitions', 'Link')
-      LinkWithOperationRef     = openapi_class.call('definitions', 'LinkWithOperationRef')
-      LinkWithOperationId     = openapi_class.call('definitions', 'LinkWithOperationId')
-      Callback               = openapi_class.call('definitions', 'Callback')
-      Encoding              = openapi_class.call('definitions', 'Encoding')
+      # 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']
+      Contact       = Document.definitions['Contact']
+      License       = Document.definitions['License']
+      Server         = Document.definitions['Server']
+      ServerVariable  = Document.definitions['ServerVariable']
+      Components       = Document.definitions['Components']
+      Schema            = Document.definitions['Schema']
+      Discriminator      = Document.definitions['Discriminator']
+      XML                 = Document.definitions['XML']
+      Response             = Document.definitions['Response']
+      MediaType             = Document.definitions['MediaType']
+      MediaTypeWithExample   = Document.definitions['MediaTypeWithExample']
+      MediaTypeWithExamples   = Document.definitions['MediaTypeWithExamples']
+      Example                  = Document.definitions['Example']
+      Header                    = Document.definitions['Header']
+      HeaderWithSchema           = Document.definitions['HeaderWithSchema']
+      HeaderWithSchemaWithExample = Document.definitions['HeaderWithSchemaWithExample']
+      HeaderWithSchemaWithExamples = Document.definitions['HeaderWithSchemaWithExamples']
+      HeaderWithContent           = Document.definitions['HeaderWithContent']
+      Paths                      = Document.definitions['Paths']
+      PathItem                    = Document.definitions['PathItem']
+      Operation                    = Document.definitions['Operation']
+      Responses                     = Document.definitions['Responses']
+      SecurityRequirement            = Document.definitions['SecurityRequirement']
+      Tag                             = Document.definitions['Tag']
+      ExternalDocumentation            = Document.definitions['ExternalDocumentation']
+      Parameter                         = Document.definitions['Parameter']
+      ParameterWithSchema                = Document.definitions['ParameterWithSchema']
+      ParameterWithSchemaWithExample      = Document.definitions['ParameterWithSchemaWithExample']
+      ParameterWithSchemaWithExampleInPath = Document.definitions['ParameterWithSchemaWithExampleInPath']
+      ParameterWithSchemaWithExampleInQuery = Document.definitions['ParameterWithSchemaWithExampleInQuery']
+      ParameterWithSchemaWithExampleInHeader = Document.definitions['ParameterWithSchemaWithExampleInHeader']
+      ParameterWithSchemaWithExampleInCookie = Document.definitions['ParameterWithSchemaWithExampleInCookie']
+      ParameterWithSchemaWithExamples       = Document.definitions['ParameterWithSchemaWithExamples']
+      ParameterWithSchemaWithExamplesInPath = Document.definitions['ParameterWithSchemaWithExamplesInPath']
+      ParameterWithSchemaWithExamplesInQuery = Document.definitions['ParameterWithSchemaWithExamplesInQuery']
+      ParameterWithSchemaWithExamplesInHeader = Document.definitions['ParameterWithSchemaWithExamplesInHeader']
+      ParameterWithSchemaWithExamplesInCookie = Document.definitions['ParameterWithSchemaWithExamplesInCookie']
+      ParameterWithContent                   = Document.definitions['ParameterWithContent']
+      ParameterWithContentInPath            = Document.definitions['ParameterWithContentInPath']
+      ParameterWithContentNotInPath        = Document.definitions['ParameterWithContentNotInPath']
+      RequestBody                         = Document.definitions['RequestBody']
+      SecurityScheme                     = Document.definitions['SecurityScheme']
+      APIKeySecurityScheme              = Document.definitions['APIKeySecurityScheme']
+      HTTPSecurityScheme               = Document.definitions['HTTPSecurityScheme']
+      NonBearerHTTPSecurityScheme     = Document.definitions['NonBearerHTTPSecurityScheme']
+      BearerHTTPSecurityScheme       = Document.definitions['BearerHTTPSecurityScheme']
+      OAuth2SecurityScheme          = Document.definitions['OAuth2SecurityScheme']
+      OpenIdConnectSecurityScheme  = Document.definitions['OpenIdConnectSecurityScheme']
+      OAuthFlows                  = Document.definitions['OAuthFlows']
+      ImplicitOAuthFlow          = Document.definitions['ImplicitOAuthFlow']
+      PasswordOAuthFlow         = Document.definitions['PasswordOAuthFlow']
+      ClientCredentialsFlow     = Document.definitions['ClientCredentialsFlow']
+      AuthorizationCodeOAuthFlow = Document.definitions['AuthorizationCodeOAuthFlow']
+      Link                      = Document.definitions['Link']
+      LinkWithOperationRef     = Document.definitions['LinkWithOperationRef']
+      LinkWithOperationId     = Document.definitions['LinkWithOperationId']
+      Callback               = Document.definitions['Callback']
+      Encoding              = Document.definitions['Encoding']
+
+      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_class = proc do |*key|
-        JSI.class_for_schema(key.inject(openapi_schema, &:[]))
-      end
+      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_class.call()
+      Document = openapi_document_schema.jsi_schema_module
 
       # naming these is not strictly necessary, but is nice to have.
-      # 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]} = openapi_class.call('definitions', '#{k}')" }`
-      Info            = openapi_class.call('definitions', 'info')
-      Contact          = openapi_class.call('definitions', 'contact')
-      License           = openapi_class.call('definitions', 'license')
-      Paths              = openapi_class.call('definitions', 'paths')
-      Definitions         = openapi_class.call('definitions', 'definitions')
-      ParameterDefinitions = openapi_class.call('definitions', 'parameterDefinitions')
-      ResponseDefinitions = openapi_class.call('definitions', 'responseDefinitions')
-      ExternalDocs       = openapi_class.call('definitions', 'externalDocs')
-      Examples          = openapi_class.call('definitions', 'examples')
-      Operation        = openapi_class.call('definitions', 'operation')
-      PathItem         = openapi_class.call('definitions', 'pathItem')
-      Responses         = openapi_class.call('definitions', 'responses')
-      ResponseValue      = openapi_class.call('definitions', 'responseValue')
-      Response            = openapi_class.call('definitions', 'response')
-      Headers              = openapi_class.call('definitions', 'headers')
-      Header                = openapi_class.call('definitions', 'header')
-      VendorExtension        = openapi_class.call('definitions', 'vendorExtension')
-      BodyParameter           = openapi_class.call('definitions', 'bodyParameter')
-      HeaderParameterSubSchema = openapi_class.call('definitions', 'headerParameterSubSchema')
-      QueryParameterSubSchema   = openapi_class.call('definitions', 'queryParameterSubSchema')
-      FormDataParameterSubSchema = openapi_class.call('definitions', 'formDataParameterSubSchema')
-      PathParameterSubSchema    = openapi_class.call('definitions', 'pathParameterSubSchema')
-      NonBodyParameter         = openapi_class.call('definitions', 'nonBodyParameter')
-      Parameter               = openapi_class.call('definitions', 'parameter')
-      Schema                 = openapi_class.call('definitions', 'schema')
-      FileSchema            = openapi_class.call('definitions', 'fileSchema')
-      PrimitivesItems        = openapi_class.call('definitions', 'primitivesItems')
-      SecurityRequirement     = openapi_class.call('definitions', 'securityRequirement')
-      Xml                      = openapi_class.call('definitions', 'xml')
-      Tag                       = openapi_class.call('definitions', 'tag')
-      SecurityDefinitions        = openapi_class.call('definitions', 'securityDefinitions')
-      BasicAuthenticationSecurity = openapi_class.call('definitions', 'basicAuthenticationSecurity')
-      ApiKeySecurity             = openapi_class.call('definitions', 'apiKeySecurity')
-      Oauth2ImplicitSecurity    = openapi_class.call('definitions', 'oauth2ImplicitSecurity')
-      Oauth2PasswordSecurity   = openapi_class.call('definitions', 'oauth2PasswordSecurity')
-      Oauth2ApplicationSecurity = openapi_class.call('definitions', 'oauth2ApplicationSecurity')
-      Oauth2AccessCodeSecurity = openapi_class.call('definitions', 'oauth2AccessCodeSecurity')
-      Oauth2Scopes            = openapi_class.call('definitions', 'oauth2Scopes')
-      Title                  = openapi_class.call('definitions', 'title')
-      Description           = openapi_class.call('definitions', 'description')
-      Default              = openapi_class.call('definitions', 'default')
-      MultipleOf          = openapi_class.call('definitions', 'multipleOf')
-      Maximum            = openapi_class.call('definitions', 'maximum')
-      ExclusiveMaximum  = openapi_class.call('definitions', 'exclusiveMaximum')
-      Minimum          = openapi_class.call('definitions', 'minimum')
-      ExclusiveMinimum = openapi_class.call('definitions', 'exclusiveMinimum')
-      MaxLength       = openapi_class.call('definitions', 'maxLength')
-      MinLength      = openapi_class.call('definitions', 'minLength')
-      Pattern       = openapi_class.call('definitions', 'pattern')
-      MaxItems     = openapi_class.call('definitions', 'maxItems')
-      MinItems    = openapi_class.call('definitions', 'minItems')
-      UniqueItems = openapi_class.call('definitions', 'uniqueItems')
-      Enum         = openapi_class.call('definitions', 'enum')
-      JsonReference = openapi_class.call('definitions', 'jsonReference')
+      # 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']
+      Paths              = Document.definitions['paths']
+      Definitions         = Document.definitions['definitions']
+      ParameterDefinitions = Document.definitions['parameterDefinitions']
+      ResponseDefinitions = Document.definitions['responseDefinitions']
+      ExternalDocs       = Document.definitions['externalDocs']
+      Examples          = Document.definitions['examples']
+      Operation        = Document.definitions['operation']
+      PathItem         = Document.definitions['pathItem']
+      Responses         = Document.definitions['responses']
+      ResponseValue      = Document.definitions['responseValue']
+      Response            = Document.definitions['response']
+      Headers              = Document.definitions['headers']
+      Header                = Document.definitions['header']
+      VendorExtension        = Document.definitions['vendorExtension']
+      BodyParameter           = Document.definitions['bodyParameter']
+      HeaderParameterSubSchema = Document.definitions['headerParameterSubSchema']
+      QueryParameterSubSchema   = Document.definitions['queryParameterSubSchema']
+      FormDataParameterSubSchema = Document.definitions['formDataParameterSubSchema']
+      PathParameterSubSchema    = Document.definitions['pathParameterSubSchema']
+      NonBodyParameter         = Document.definitions['nonBodyParameter']
+      Parameter               = Document.definitions['parameter']
+      Schema                 = Document.definitions['schema']
+      FileSchema            = Document.definitions['fileSchema']
+      PrimitivesItems        = Document.definitions['primitivesItems']
+      SecurityRequirement     = Document.definitions['securityRequirement']
+      Xml                      = Document.definitions['xml']
+      Tag                       = Document.definitions['tag']
+      SecurityDefinitions        = Document.definitions['securityDefinitions']
+      BasicAuthenticationSecurity = Document.definitions['basicAuthenticationSecurity']
+      ApiKeySecurity             = Document.definitions['apiKeySecurity']
+      Oauth2ImplicitSecurity    = Document.definitions['oauth2ImplicitSecurity']
+      Oauth2PasswordSecurity   = Document.definitions['oauth2PasswordSecurity']
+      Oauth2ApplicationSecurity = Document.definitions['oauth2ApplicationSecurity']
+      Oauth2AccessCodeSecurity = Document.definitions['oauth2AccessCodeSecurity']
+      Oauth2Scopes            = Document.definitions['oauth2Scopes']
+      Title                  = Document.definitions['title']
+      Description           = Document.definitions['description']
+      Default              = Document.definitions['default']
+      MultipleOf          = Document.definitions['multipleOf']
+      Maximum            = Document.definitions['maximum']
+      ExclusiveMaximum  = Document.definitions['exclusiveMaximum']
+      Minimum          = Document.definitions['minimum']
+      ExclusiveMinimum = Document.definitions['exclusiveMinimum']
+      MaxLength       = Document.definitions['maxLength']
+      MinLength      = Document.definitions['minLength']
+      Pattern       = Document.definitions['pattern']
+      MaxItems     = Document.definitions['maxItems']
+      MinItems    = Document.definitions['minItems']
+      UniqueItems = Document.definitions['uniqueItems']
+      Enum         = Document.definitions['enum']
+      JsonReference = Document.definitions['jsonReference']
+
+      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
-      class Operation
+      module Operation
         include OpenAPI::Operation
       end
-      class Document
+      module Document
         include OpenAPI::Document
       end
+      module Reference
+        include OpenAPI::Reference
+      end
+      module Tag
+        include OpenAPI::Tag
+      end
       require 'scorpio/openapi/v3/server'
     end
 
     module V2
-      class Operation
+      module Operation
         include OpenAPI::Operation
       end
-      class Document
+      module Document
         include OpenAPI::Document
       end
+      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,6 +1,10 @@
+# frozen_string_literal: true
+
 module Scorpio
   class Request
-    SUPPORTED_REQUEST_MEDIA_TYPES = ['application/json', '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
         media_types.first
@@ -116,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
@@ -146,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 " +
@@ -172,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
@@ -197,10 +205,11 @@ 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 || ::Ur::ContentType.new(media_type)
+      content_type_header || (media_type ? ::Ur::ContentType.new(media_type) : nil)
     end
 
     # @return [::JSI::Schema]
@@ -208,11 +217,6 @@ module Scorpio
       operation.request_schema(media_type: media_type)
     end
 
-    # @return [Class subclassing JSI::Base]
-    def request_schema_class(media_type: self.media_type)
-      JSI.class_for_schema(request_schema(media_type: media_type))
-    end
-
     # builds a Faraday connection with this Request's faraday_builder and faraday_adapter.
     # passes a given proc yield_ur to middleware to yield an Ur for requests made with the connection.
     #
@@ -222,8 +226,9 @@ module Scorpio
       Faraday.new do |faraday_connection|
         faraday_builder.call(faraday_connection)
         if yield_ur
-          ::Ur::Faraday # autoload trigger
-          faraday_connection.response(:yield_ur, ur_class: Scorpio::Ur, logger: self.logger, &yield_ur)
+          -> { ::Ur::Faraday }.() # autoload trigger
+
+          faraday_connection.response(:yield_ur, schemas: Set[Scorpio::Ur.schema], logger: self.logger, &yield_ur)
         end
         faraday_connection.adapter(*faraday_adapter)
       end
@@ -234,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'])
@@ -251,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 }
@@ -265,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)
@@ -294,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'
@@ -322,24 +335,30 @@ module Scorpio
       if user_agent
         headers['User-Agent'] = user_agent
       end
-      if media_type && !content_type_header
-        headers['Content-Type'] = media_type
+      if !content_type_header
+        if media_type
+          headers['Content-Type'] = media_type
+        else
+          # I'd rather not have a default content-type, but if none is set then the HTTP adapter sets this to 
+          # application/x-www-form-urlencoded and issues a warning about it.
+          headers['Content-Type'] = FALLBACK_CONTENT_TYPE
+        end
       end
       if self.headers
         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