scorpio 0.3.1 → 0.4.0

data/lib/scorpio.rb

@@ -19,8 +19,18 @@ module Scorpio
   end
 
   proc { |v| define_singleton_method(:error_classes_by_status) { v } }.call({})
+  # Scorpio::Error encompasses certain Scorpio-defined errors encountered in using Scorpio.
+  # at the moment this only includes HTTPError[^1], but will likely cover errors in schemas and
+  # other things in the future.
+  #
+  # [^1]: unless I have, since writing this, implemented other things but forgotten to update this
+  # comment, which does seem likely enough.
   class Error < StandardError; end
   class HTTPError < Error
+    # for HTTPError subclasses representing a single status, sets and/or returns the represented status.
+    #
+    # @param status [Integer] if specified, sets the HTTP status the class represents
+    # @return [Integer] the HTTP status the class represents
     def self.status(status = nil)
       if status
         @status = status
@@ -35,7 +45,9 @@ module Scorpio
   # be referred to like Scorpio::BadRequest400Error. this is just to avoid clutter in the Scorpio
   # namespace in yardoc.
   module HTTPErrors
+    # an HTTP response with a status of 400-499
     class ClientError < HTTPError; end
+    # an HTTP response with a status of 500-599
     class ServerError < HTTPError; end
 
     class BadRequest400Error < ClientError;                    status(400); end
@@ -82,6 +94,12 @@ module Scorpio
   include HTTPErrors
   error_classes_by_status.freeze
 
+  class ConfigError < Error
+    attr_accessor :name
+  end
+  class AmbiguousParameter < ConfigError
+  end
+
   autoload :Google, 'scorpio/google_api_document'
   autoload :OpenAPI, 'scorpio/openapi'
   autoload :Ur, 'scorpio/ur'

data/lib/scorpio/openapi.rb

@@ -5,7 +5,7 @@ module Scorpio
     autoload :OperationsScope, 'scorpio/openapi/operations_scope'
 
     module V3
-      openapi_schema = JSI::Schema.new(::JSON.parse(Scorpio.root.join('documents/openapis.org/v3/schema.json').read))
+      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
@@ -13,66 +13,67 @@ module Scorpio
       Document = openapi_class.call()
 
       # naming these is not strictly necessary, but is nice to have.
-      # 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]} = openapi_class.call('definitions', '#{k}')" }
-      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')
-      Paths        = openapi_class.call('definitions', 'paths')
-      PathItem    = openapi_class.call('definitions', 'pathItem')
-      Operation   = openapi_class.call('definitions', 'operation')
-      ExternalDocs = openapi_class.call('definitions', 'externalDocs')
-      Parameter   = openapi_class.call('definitions', 'parameter')
-      RequestBody = openapi_class.call('definitions', 'requestBody')
-      MediaType  = openapi_class.call('definitions', 'mediaType')
-      Encoding  = openapi_class.call('definitions', 'encoding')
-      Responses = openapi_class.call('definitions', 'responses')
-      Response = openapi_class.call('definitions', 'response')
-      Callback = openapi_class.call('definitions', 'callback')
-      Example = openapi_class.call('definitions', 'example')
-      Link     = openapi_class.call('definitions', 'link')
-      Header    = openapi_class.call('definitions', 'header')
-      Tag        = openapi_class.call('definitions', 'tag')
-      Examples    = openapi_class.call('definitions', 'examples')
-      Reference    = openapi_class.call('definitions', 'reference')
-      Schema        = openapi_class.call('definitions', 'schema')
-      Discriminator  = openapi_class.call('definitions', 'discriminator')
-      Xml             = openapi_class.call('definitions', 'xml')
-      SecurityScheme   = openapi_class.call('definitions', 'securityScheme')
-      OauthFlows        = openapi_class.call('definitions', 'oauthFlows')
-      OauthFlow          = openapi_class.call('definitions', 'oauthFlow')
-      SecurityRequirement = openapi_class.call('definitions', 'securityRequirement')
-      AnyOrExpression    = openapi_class.call('definitions', 'anyOrExpression')
-      CallbackOrReference = openapi_class.call('definitions', 'callbackOrReference')
-      ExampleOrReference = openapi_class.call('definitions', 'exampleOrReference')
-      HeaderOrReference   = openapi_class.call('definitions', 'headerOrReference')
-      LinkOrReference      = openapi_class.call('definitions', 'linkOrReference')
-      ParameterOrReference  = openapi_class.call('definitions', 'parameterOrReference')
-      RequestBodyOrReference = openapi_class.call('definitions', 'requestBodyOrReference')
-      ResponseOrReference     = openapi_class.call('definitions', 'responseOrReference')
-      SchemaOrReference        = openapi_class.call('definitions', 'schemaOrReference')
-      SecuritySchemeOrReference = openapi_class.call('definitions', 'securitySchemeOrReference')
-      AnysOrExpressions        = openapi_class.call('definitions', 'anysOrExpressions')
-      CallbacksOrReferences   = openapi_class.call('definitions', 'callbacksOrReferences')
-      Encodings              = openapi_class.call('definitions', 'encodings')
-      ExamplesOrReferences  = openapi_class.call('definitions', 'examplesOrReferences')
-      HeadersOrReferences   = openapi_class.call('definitions', 'headersOrReferences')
-      LinksOrReferences      = openapi_class.call('definitions', 'linksOrReferences')
-      MediaTypes              = openapi_class.call('definitions', 'mediaTypes')
-      ParametersOrReferences   = openapi_class.call('definitions', 'parametersOrReferences')
-      RequestBodiesOrReferences = openapi_class.call('definitions', 'requestBodiesOrReferences')
-      ResponsesOrReferences     = openapi_class.call('definitions', 'responsesOrReferences')
-      SchemasOrReferences        = openapi_class.call('definitions', 'schemasOrReferences')
-      SecuritySchemesOrReferences = openapi_class.call('definitions', 'securitySchemesOrReferences')
-      ServerVariables            = openapi_class.call('definitions', 'serverVariables')
-      Strings                   = openapi_class.call('definitions', 'strings')
-      Object                   = openapi_class.call('definitions', 'object')
-      Any                     = openapi_class.call('definitions', 'any')
-      Expression             = openapi_class.call('definitions', 'expression')
-      SpecificationExtension = openapi_class.call('definitions', 'specificationExtension')
-      DefaultType           = openapi_class.call('definitions', 'defaultType')
+      # 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')
     end
     module V2
       openapi_schema = JSI::Schema.new(::JSON.parse(Scorpio.root.join('documents/swagger.io/v2/schema.json').read))
@@ -83,7 +84,7 @@ module Scorpio
       Document = openapi_class.call()
 
       # 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}')" }
+      # 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')

data/lib/scorpio/openapi/document.rb

@@ -1,7 +1,16 @@
 module Scorpio
   module OpenAPI
+    # A document that defines or describes an API.
+    # An OpenAPI definition uses and conforms to the OpenAPI Specification.
+    #
+    # Scorpio::OpenAPI::Document is a module common to V2 and V3 documents.
     module Document
       class << self
+        # takes a document, generally a Hash, and returns a Scorpio OpenAPI Document
+        # instantiating it.
+        #
+        # @param instance [#to_hash] the document to represent as a Scorpio OpenAPI Document
+        # @return [Scorpio::OpenAPI::V2::Document, Scorpio::OpenAPI::V3::Document]
         def from_instance(instance)
           if instance.is_a?(Hash)
             instance = JSI::JSON::Node.new_doc(instance)
@@ -76,6 +85,10 @@ module Scorpio
 
     module V3
       raise(Bug) unless const_defined?(:Document)
+
+      # A document that defines or describes an API conforming to the OpenAPI Specification v3.
+      #
+      # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#oasObject
       class Document
         module Configurables
           def scheme
@@ -115,6 +128,10 @@ module Scorpio
 
     module V2
       raise(Bug) unless const_defined?(:Document)
+
+      # A document that defines or describes an API conforming to the OpenAPI Specification v2 (aka Swagger).
+      #
+      # The root document is known as the Swagger Object.
       class Document
         module Configurables
           attr_writer :scheme

data/lib/scorpio/openapi/operation.rb

@@ -1,5 +1,8 @@
 module Scorpio
   module OpenAPI
+    # An OpenAPI operation
+    #
+    # Scorpio::OpenAPI::Operation is a module common to V2 and V3 operations.
     module Operation
       module Configurables
         attr_writer :base_url
@@ -40,13 +43,24 @@ module Scorpio
       end
       include Configurables
 
+      # @return [Boolean] v3?
+      def v3?
+        is_a?(V3::Operation)
+      end
+
+      # @return [Boolean] v2?
+      def v2?
+        is_a?(V2::Operation)
+      end
+
+      # @return [Scorpio::OpenAPI::Document] the document whence this operation came
       def openapi_document
         parents.detect { |p| p.is_a?(Scorpio::OpenAPI::Document) }
       end
 
-      def path
-        return @path if instance_variable_defined?(:@path)
-        @path = begin
+      def path_template_str
+        return @path_template_str if instance_variable_defined?(:@path_template_str)
+        @path_template_str = begin
           parent_is_pathitem = parent.is_a?(Scorpio::OpenAPI::V2::PathItem) || parent.is_a?(Scorpio::OpenAPI::V3::PathItem)
           parent_parent_is_paths = parent.parent.is_a?(Scorpio::OpenAPI::V2::Paths) || parent.parent.is_a?(Scorpio::OpenAPI::V3::Paths)
           if parent_is_pathitem && parent_parent_is_paths
@@ -55,6 +69,24 @@ module Scorpio
         end
       end
 
+      # @return [Addressable::Template] the path as an Addressable::Template
+      def path_template
+        return @path_template if instance_variable_defined?(:@path_template)
+        @path_template = Addressable::Template.new(path_template_str)
+      end
+
+      # @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
+      def uri_template(base_url: self.base_url)
+        unless base_url
+          raise(ArgumentError, "no base_url has been specified for operation #{self}")
+        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::Template.new(File.join(base_url, path_template_str))
+      end
+
       def http_method
         return @http_method if instance_variable_defined?(:@http_method)
         @http_method = begin
@@ -65,6 +97,49 @@ module Scorpio
         end
       end
 
+      # 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
+      def inferred_parameters
+        parameters = self.parameters ? self.parameters.to_a.dup : []
+        path_template.variables.each do |var|
+          unless parameters.any? { |p| p['in'] == 'path' && p['name'] == var }
+            # we could instantiate this as a V2::Parameter or a V3::Parameter
+            # or a ParameterWithContentInPath or whatever. but I can't be bothered.
+            parameters << {
+              'name' => var,
+              'in' => 'path',
+              'required' => true,
+              'type' => 'string',
+            }
+          end
+        end
+        parameters
+      end
+
+      # @return [Module] a module with accessor methods for unambiguously named parameters of this operation.
+      def request_accessor_module
+        return @request_accessor_module if instance_variable_defined?(:@request_accessor_module)
+        @request_accessor_module = begin
+          params_by_name = inferred_parameters.group_by { |p| p['name'] }
+          Module.new do
+            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, &:|)
+            params_by_name.each do |name, params|
+              next if instance_method_names.include?(name)
+              if params.size == 1
+                param = params.first
+                define_method("#{name}=") { |value| set_param_from(param['in'], param['name'], value) }
+                define_method(name) { get_param_from(param['in'], param['name']) }
+              end
+            end
+          end
+        end
+      end
+
       def build_request(*a, &b)
         request = Scorpio::Request.new(self, *a, &b)
       end
@@ -80,9 +155,14 @@ module Scorpio
 
     module V3
       raise(Bug) unless const_defined?(:Operation)
+
+      # 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 Configurables
           def scheme
+            # not applicable; for OpenAPI v3, scheme is specified by servers.
             nil
           end
 
@@ -177,18 +257,20 @@ module Scorpio
           elsif body_parameters.size == 1
             body_parameters.first
           else
-            raise(Bug) # TODO BLAME
+            raise(Bug, "multiple body parameters on operation #{operation.pretty_inspect.chomp}") # TODO BLAME
           end
         end
 
         def request_schema(media_type: nil)
           if body_parameter && body_parameter['schema']
             JSI::Schema.new(body_parameter['schema'])
+          else
+            nil
           end
         end
 
         def request_schemas
-          [request_schema]
+          request_schema ? [request_schema] : []
         end
 
         # @return JSI::Schema

data/lib/scorpio/openapi/operations_scope.rb

@@ -1,13 +1,17 @@
 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
       end
       attr_reader :openapi_document
 
+      # @yield [Scorpio::OpenAPI::Operation]
       def each
         openapi_document.paths.each do |path, path_item|
           path_item.each do |http_method, operation|
@@ -19,9 +23,11 @@ module Scorpio
       end
       include Enumerable
 
-      def [](operationId_)
-        memoize(:[], operationId_) do |operationId|
-          detect { |operation| operation.operationId == operationId }
+      # @param operationId
+      # @return [Scorpio::OpenAPI::Operation] the operation with the given operationId
+      def [](operationId)
+        memoize(:[], operationId) do |operationId_|
+          detect { |operation| operation.operationId == operationId_ }
         end
       end
     end

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

@@ -2,7 +2,17 @@ module Scorpio
   module OpenAPI
     module V3
       raise(Bug) unless const_defined?(:Server)
+
+      # An object representing a Server.
+      #
+      # https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#serverObject
       class 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.
+        #
+        # @param given_server_variables [Hash<String, String>]
+        # @return [Addressable::URI] the expanded url
         def expanded_url(given_server_variables)
           if variables
             server_variables = (given_server_variables.keys | variables.keys).map do |key|

data/lib/scorpio/request.rb

@@ -110,45 +110,72 @@ module Scorpio
     end
     include Configurables
 
-    def initialize(operation, **configuration, &b)
-      configuration.each do |k, v|
-        settername = "#{k}="
-        if Configurables.public_method_defined?(settername)
-          Configurables.instance_method(settername).bind(self).call(v)
+    # @param operation [Scorpio::OpenAPI::Operation]
+    # @param configuration [#to_hash] a hash keyed with configurable attributes for
+    #   the request - instance methods of Scorpio::Request::Configurables, whose values
+    #   will be assigned for those attributes.
+    def initialize(operation, configuration = {}, &b)
+      @operation = operation
+
+      configuration = JSI.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)
+          params_set << name
+        end
+      end
+      # then do other top-level params
+      configuration.reject { |name, _| params_set.include?(name) }.each do |name, value|
+        params = operation.inferred_parameters.select { |p| p['name'] == name }
+        if params.size == 1
+          set_param_from(params.first['in'], name, value)
+        elsif params.size == 0
+          raise(ArgumentError, "unrecognized configuration value passed: #{name.inspect}")
         else
-          raise(ArgumentError, "unsupported configuration value passed: #{k.inspect} => #{v.inspect}")
+          raise(AmbiguousParameter.new("There are multiple parameters named #{name.inspect} - cannot use it as a configuration key").tap { |e| e.name = name })
         end
       end
 
-      @operation = operation
+      extend operation.request_accessor_module
+
       if block_given?
         yield self
       end
     end
 
+    # @return [Scorpio::OpenAPI::Operation]
     attr_reader :operation
 
+    # @return [Scorpio::OpenAPI::Document]
     def openapi_document
       operation.openapi_document
     end
 
+    # @return [Symbol] the http method for this request - :get, :post, etc.
     def http_method
       operation.http_method.downcase.to_sym
     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
     def path_template
-      Addressable::Template.new(operation.path)
+      operation.path_template
     end
 
+    # @return [Addressable::URI] an Addressable::URI containing only the path to append to
+    #   the base_url for this request
     def path
+      path_params = JSI.stringify_symbol_keys(self.path_params)
       missing_variables = path_template.variables - path_params.keys
       if missing_variables.any?
-        raise(ArgumentError, "path #{operation.path} for operation #{operation.operationId} requires path_params " +
+        raise(ArgumentError, "path #{operation.path_template_str} for operation #{operation.operationId} requires path_params " +
           "which were missing: #{missing_variables.inspect}")
       end
       empty_variables = path_template.variables.select { |v| path_params[v].to_s.empty? }
       if empty_variables.any?
-        raise(ArgumentError, "path #{operation.path} for operation #{operation.operationId} requires path_params " +
+        raise(ArgumentError, "path #{operation.path_template_str} for operation #{operation.operationId} requires path_params " +
           "which were empty: #{empty_variables.inspect}")
       end
 
@@ -159,20 +186,22 @@ module Scorpio
       end
     end
 
+    # @return [Addressable::URI] the full URL for this request
     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.
-      url = File.join(base_url, path)
-      url = Addressable::URI.parse(url)
+      Addressable::URI.parse(File.join(base_url, path))
     end
 
+    # @return [::Ur::ContentTypeAttrs] content type attributes for this request's Content-Type
     def content_type_attrs
       Ur::ContentTypeAttrs.new(content_type)
     end
 
+    # @return [String] the value of the request Content-Type header
     def content_type_header
       headers.each do |k, v|
         return v if k =~ /\Acontent[-_]type\z/i
@@ -180,18 +209,27 @@ module Scorpio
       nil
     end
 
+    # @return [String] Content-Type for this request, taken from request headers if
+    #   present, or the request media_type.
     def content_type
       content_type_header || media_type
     end
 
+    # @return [::JSI::Schema]
     def request_schema(media_type: self.media_type)
       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.
+    #
+    # @param yield_ur [Proc]
+    # @return [::Faraday::Connection]
     def faraday_connection(yield_ur = nil)
       Faraday.new do |faraday_connection|
         faraday_builder.call(faraday_connection)
@@ -203,6 +241,81 @@ module Scorpio
       end
     end
 
+    # if there is only one parameter with the given name, of any sort, this will set it.
+    #
+    # @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 paramater has the given name
+    def set_param(name, value)
+      name = name.to_s if name.is_a?(Symbol)
+      params = operation.inferred_parameters.select { |p| p['name'] == name }
+      if params.size == 1
+        set_param_from(params.first['in'], name, value)
+      else
+        raise(AmbiguousParameter.new("There are multiple parameters named #{name}; cannot use #set_param").tap { |e| e.name = name })
+      end
+      value
+    end
+
+    # @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 paramater has the given name
+    def get_param(name)
+      name = name.to_s if name.is_a?(Symbol)
+      params = operation.inferred_parameters.select { |p| p['name'] == name }
+      if params.size == 1
+        get_param_from(params.first['in'], name)
+      else
+        raise(AmbiguousParameter.new("There are multiple parameters named #{name}; cannot use #get_param").tap { |e| e.name = name })
+      end
+    end
+
+    # @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 [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)
+      name = name.to_s if name.is_a?(Symbol)
+      if param_in == 'path'
+        self.path_params = self.path_params.merge(name => value)
+      elsif param_in == 'query'
+        self.query_params = (self.query_params || {}).merge(name => value)
+      elsif param_in == 'header'
+        self.headers = self.headers.merge(name => value)
+      elsif param_in == 'cookie'
+        raise(NotImplementedError, "cookies not implemented: #{name.inspect} => #{value.inspect}")
+      else
+        raise(ArgumentError, "cannot set param from param_in = #{param_in.inspect} (name: #{name.pretty_inspect.chomp}, value: #{value.pretty_inspect.chomp})")
+      end
+      value
+    end
+
+    # @param in [String, Symbol] one of 'path', 'query', 'header', or 'cookie' - where to apply 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
+    # @raise [NotImplementedError] cookies aren't implemented
+    def get_param_from(param_in, name)
+      if param_in == 'path'
+        path_params[name]
+      elsif param_in == 'query'
+        query_params ? query_params[name] : nil
+      elsif param_in == 'header'
+        headers[name]
+      elsif param_in == 'cookie'
+        raise(NotImplementedError, "cookies not implemented: #{name.inspect}")
+      else
+        raise(ArgumentError, "cannot get param from param_in = #{param_in.inspect} (name: #{name.pretty_inspect.chomp})")
+      end
+    end
+
+    # runs this request and returns the full representation of the request that was run and its response.
+    #
+    # @return [Scorpio::Ur]
     def run_ur
       headers = {}
       if user_agent
@@ -220,10 +333,33 @@ module Scorpio
       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.
+    #
+    # @raise [Scorpio::HTTPError] if the request returns a 4xx or 5xx status, the appropriate
+    #   error is raised - see Scorpio::HTTPErrors
     def run
       ur = run_ur
       ur.raise_on_http_error
       ur.response.body_object
     end
+
+    # todo make a proper iterator interface
+    # @param next_page [#call] a callable which will take a parameter `page_ur`, which is a {Scorpio::Ur},
+    #   and must result in an Ur representing the next page, which will be yielded to the block.
+    # @yield [Scorpio::Ur] yields the first page, and each subsequent result of calls to `next_page` until
+    #   that results in nil
+    # @return [void]
+    def each_page_ur(next_page: , raise_on_http_error: true)
+      return to_enum(__method__, next_page: next_page, raise_on_http_error: raise_on_http_error) unless block_given?
+      page_ur = run_ur
+      while page_ur
+        page_ur.raise_on_http_error if raise_on_http_error
+        yield page_ur
+        page_ur = next_page.call(page_ur)
+      end
+      nil
+    end
   end
 end