verquest 0.6.4 → 0.7.0

data/docs/rails.md

@@ -0,0 +1,169 @@
+# Rails and rswag
+
+Verquest doesn't depend on Rails, so it ships no Rails integration. Its three locations map onto Rails request methods, though: `location :body` (the default) reads `request_parameters`, `location :query` reads `query_parameters`, and `location :path` reads `path_parameters`. This guide gives you two small pieces to copy into your app:
+
+- a controller concern that processes all three from one declaration per class;
+- an rswag shared context that documents query and path classes in your request specs.
+
+## API version
+
+Verquest picks the request version from `config.current_version`. With the version in the URL (`/2025-06/deals`), keep it in `Current` and read it from there:
+
+```ruby
+# config/routes.rb
+scope "/:api_version", constraints: {api_version: /\d{4}-\d{2}/} do
+  resources :deals, only: %i[index show update] do
+    resource :win, only: :create, module: :deals
+  end
+end
+
+# app/models/current.rb
+class Current < ActiveSupport::CurrentAttributes
+  attribute :api_version
+end
+
+# config/initializers/verquest.rb
+Verquest.configure do |config|
+  config.current_version = -> { Current.api_version }
+end
+```
+
+## Controller concern
+
+```ruby
+# app/controllers/concerns/verquest_params.rb
+module VerquestParams
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :process_verquest_params
+    attr_reader :body_params, :query_params, :path_params
+
+    # Keep JSON bodies as sent, without a copy under the controller's name
+    wrap_parameters false
+  end
+
+  class_methods do
+    # `param:` is the route key a path class's `id` comes from
+    def verquest_params(request_class, param: :id, only: nil, except: nil)
+      verquest_declarations << {class: request_class, param:, only: Array(only), except: Array(except)}
+    end
+
+    def verquest_declarations
+      @verquest_declarations ||= []
+    end
+  end
+
+  private
+
+  def process_verquest_params
+    declarations = self.class.verquest_declarations.select { |declaration| verquest_declaration_applies?(declaration) }
+    by_location = declarations.group_by { |declaration| declaration[:class].location }
+
+    # Every path class applies, so /deals/:deal_id/notes/:id can check both IDs
+    @path_params = by_location.fetch(:path, []).to_h { |declaration| process_path_param(declaration) }
+    # Unknown query keys (cache busters, tracking) are dropped instead of rejected
+    @query_params = by_location[:query]&.first&.dig(:class)&.process(request.query_parameters, remove_extra_root_keys: true)
+    @body_params = by_location[:body]&.first&.dig(:class)&.process(request.request_parameters)
+  end
+
+  def process_path_param(declaration)
+    param = declaration[:param]
+    [param.to_s, declaration[:class].process({"id" => request.path_parameters[param]})["id"]]
+  rescue Verquest::InvalidParamsError => e
+    # Point errors at the route key (/deal_id), not the class's /id
+    errors = e.errors.map { |error| error.merge(pointer: "/#{param}", message: error[:message].sub("`/id`", "`/#{param}`")) }
+    raise Verquest::InvalidParamsError.new(e.message, errors:)
+  end
+
+  def verquest_declaration_applies?(declaration)
+    action = action_name.to_sym
+    (declaration[:only].empty? || declaration[:only].include?(action)) && declaration[:except].exclude?(action)
+  end
+end
+```
+
+The concern expects `config.validation_error_handling = :raise` (the default). Set the version and render errors once, in the base controller:
+
+```ruby
+class ApplicationController < ActionController::API
+  # Declared before the include, so the version is set when the concern's before_action runs
+  before_action { Current.api_version = params[:api_version] }
+  include VerquestParams
+
+  rescue_from Verquest::InvalidParamsError do |error|
+    render json: {errors: error.errors}, status: :unprocessable_content
+  end
+end
+```
+
+Each path class validates one ID as `id`, so one class serves both the member route (`/deals/:id`) and nested routes (`/deals/:deal_id/win`):
+
+```ruby
+class DealPath < Verquest::Base
+  location :path
+
+  version "2025-06" do
+    field :id, type: :string, required: true, pattern: "^deal_", description: "The ID of the deal"
+  end
+end
+```
+
+```ruby
+class DealsController < ApplicationController
+  verquest_params DealPath, only: %i[show update]
+  verquest_params DealsIndexQuery, only: :index
+  verquest_params DealUpdateRequest, only: :update
+
+  def show
+    render json: Deal.find_by!(public_id: path_params["id"])
+  end
+end
+
+class Deals::WinsController < ApplicationController
+  verquest_params DealPath, param: :deal_id # POST /deals/:deal_id/win
+end
+```
+
+`GET /deals/con_123` then returns 422 with `{"pointer" => "/id", ...}`, and `POST /deals/con_123/win` with `{"pointer" => "/deal_id", ...}`.
+
+## rswag
+
+A shared context documents a query or path class with `to_parameters`. `name:` renames a path class's parameter to the route key, and `description:` replaces its description:
+
+```ruby
+# spec/support/verquest.rb
+RSpec.shared_context "verquest parameters" do |request_class, version:, name: nil, description: nil|
+  request_class.to_parameters(version:).each do |attributes|
+    parameter(attributes.merge({name:, description:}.compact))
+  end
+end
+```
+
+```ruby
+path "/2025-06/deals/{deal_id}" do
+  include_context "verquest parameters", DealPath, version: "2025-06", name: "deal_id"
+
+  patch "Update a deal" do
+    include_context "verquest parameters", ExpandQuery, version: "2025-06"
+    parameter name: :payload, in: :body, schema: {"$ref" => DealUpdateRequest.to_ref}
+
+    response "200", "deal updated" do
+      let(:deal_id) { create(:deal).public_id }
+      let(:payload) { {name: "New name"} }
+
+      run_test!
+    end
+  end
+end
+```
+
+rswag skips optional query parameters without a matching `let`, so specs only define the ones they send.
+
+Body classes are registered as components in `swagger_helper.rb` (see [Component Generation for OpenAPI](../README.md#component-generation-for-openapi)):
+
+```ruby
+components: {
+  schemas: [DealUpdateRequest].to_h { |request| [request.component_name, request.to_schema(version: "2025-06")] }
+}
+```

data/lib/verquest/base/condition_class_methods.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module Verquest
+  # DSL class methods for conditional schemas (`if` / `then` / `else`)
+  #
+  # `condition` opens a {Verquest::Conditions::Condition} on the current scope.
+  # `given`, `then_apply` and `else_apply` make its parts the current scope, so
+  # `field`, `object` and the rest add branch properties exactly as they add
+  # regular ones, and the rule methods add rules.
+  #
+  # @example
+  #   version "2025-09" do
+  #     field :kind, type: :string
+  #
+  #     condition :company do
+  #       given { equals :kind, "company" }
+  #       then_apply { field :vat_id, type: :string, required: true }
+  #     end
+  #   end
+  #
+  # @api private
+  module Base::ConditionClassMethods
+    private
+
+    # Declares a condition on the current scope
+    #
+    # @param name [Symbol, nil] Optional name, used to exclude the condition in a later version
+    # @param document_as [Symbol, nil] `:one_of` to document the condition as a oneOf of its branches
+    #   in `to_schema`, while validation keeps `if` / `then` / `else`. Only for a condition in a version.
+    # @yield Block declaring `given`, `then_apply` and `else_apply`
+    # @return [void]
+    # @raise [ArgumentError] If the current scope can't hold conditions, or document_as is used outside a version
+    def condition(name = nil, document_as: nil, &block)
+      raise ArgumentError, "condition can only be declared in a version, object or inline collection" unless current_scope.respond_to?(:add_condition)
+      raise ArgumentError, "document_as: :one_of can only be used on a condition in a version" if document_as && !current_scope.is_a?(Version)
+
+      condition = Conditions::Condition.new(name:, document_as:)
+      current_scope.add_condition(condition)
+      within_scope(condition, &block)
+    end
+
+    # Declares the `if` of the current condition
+    #
+    # @yield Block declaring rules
+    # @return [void]
+    def given(&block)
+      open_condition_part(:given, &block)
+    end
+
+    # Declares the `then` of the current condition
+    #
+    # The title, description and deprecated flag document the branch's
+    # variant when the condition is declared with `document_as: :one_of`.
+    #
+    # @param title [String, nil] Title of the branch's oneOf variant
+    # @param description [String, nil] Description of the branch's oneOf variant
+    # @param deprecated [Boolean, nil] Whether the branch's oneOf variant is deprecated
+    # @yield Block declaring rules and properties
+    # @return [void]
+    def then_apply(title: nil, description: nil, deprecated: nil, &block)
+      open_condition_part(:then, title:, description:, deprecated:, &block)
+    end
+
+    # Declares the `else` of the current condition
+    #
+    # The title, description and deprecated flag document the branch's
+    # variant when the condition is declared with `document_as: :one_of`.
+    #
+    # @param title [String, nil] Title of the branch's oneOf variant
+    # @param description [String, nil] Description of the branch's oneOf variant
+    # @param deprecated [Boolean, nil] Whether the branch's oneOf variant is deprecated
+    # @yield Block declaring rules and properties
+    # @return [void]
+    def else_apply(title: nil, description: nil, deprecated: nil, &block)
+      open_condition_part(:else, title:, description:, deprecated:, &block)
+    end
+
+    # Declares a condition that applies the block when a property is present
+    #
+    # Shorthand for `condition(name) { given { present key }; then_apply { ... } }`.
+    #
+    # @param key [Symbol] The property whose presence triggers the block
+    # @param name [Symbol, nil] Optional condition name
+    # @yield Block declaring rules and properties, like `then_apply`
+    # @return [void]
+    def depends_on(key, name = nil, &block)
+      condition(name) do
+        given { present key }
+        then_apply(&block)
+      end
+    end
+
+    # Removes inherited named conditions from the current version
+    #
+    # A named condition can be declared only once per version, so exclude an
+    # inherited one before declaring a condition with the same name.
+    #
+    # @param names [Array<Symbol>] The condition names
+    # @return [void]
+    # @raise [ArgumentError] If a condition is not defined
+    def exclude_conditions(*names)
+      names.each { |name| current_scope.remove_condition(name) }
+    end
+
+    # Requires the named properties to be present
+    #
+    # @param names [Array<Symbol>] The property names
+    # @return [void]
+    def present(*names)
+      add_rule(Conditions::Rules::Present.new(names))
+    end
+
+    # Forbids the named properties
+    #
+    # @param names [Array<Symbol>] The property names
+    # @return [void]
+    def absent(*names)
+      add_rule(Conditions::Rules::Absent.new(names))
+    end
+
+    # Requires a property to hold one value
+    #
+    # @param name [Symbol] The property name
+    # @param value [Object] The value
+    # @return [void]
+    def equals(name, value)
+      add_rule(Conditions::Rules::Equals.new(name, value))
+    end
+
+    # Requires a property to hold one of several values
+    #
+    # @param name [Symbol] The property name
+    # @param values [Array] The values
+    # @return [void]
+    def value_in(name, values)
+      add_rule(Conditions::Rules::ValueIn.new(name, values))
+    end
+
+    # Requires a property to match schema options (camelized like field options)
+    #
+    # @param name [Symbol] The property name
+    # @param schema_options [Hash] The schema options
+    # @return [void]
+    def satisfies(name, **schema_options)
+      add_rule(Conditions::Rules::Satisfies.new(name, camelize(schema_options)))
+    end
+
+    # Requires at least one of the rules in the block to hold
+    #
+    # @yield Block declaring the alternative rules
+    # @return [void]
+    def any(&block)
+      add_rule_set(Conditions::Rules::Any.new, &block)
+    end
+
+    # Requires none of the rules in the block to hold
+    #
+    # @yield Block declaring the rules
+    # @return [void]
+    def none(&block)
+      add_rule_set(Conditions::Rules::None.new, &block)
+    end
+
+    # Makes a part of the current condition the scope for the block
+    #
+    # @param part [Symbol] :given, :then or :else
+    # @yield Block declaring the part
+    # @return [void]
+    # @raise [ArgumentError] If the current scope is not a condition
+    def open_condition_part(part, **options, &block)
+      raise ArgumentError, "given, then_apply and else_apply can only be used inside a condition" unless current_scope.is_a?(Conditions::Condition)
+
+      within_scope(current_scope.open(part, **options), &block)
+    end
+
+    # Adds a rule to the current scope
+    #
+    # @param rule [#to_schema, #property_names] The rule
+    # @return [void]
+    # @raise [ArgumentError] If the current scope can't hold rules
+    def add_rule(rule)
+      raise ArgumentError, "Rules can only be used inside given, then_apply, else_apply, depends_on, any or none" unless current_scope.respond_to?(:add_rule)
+
+      current_scope.add_rule(rule)
+    end
+
+    # Adds a rule that holds other rules and makes it the scope for the block
+    #
+    # @param rule_set [Verquest::Conditions::Rules::Any] The rule
+    # @yield Block declaring the nested rules
+    # @return [void]
+    def add_rule_set(rule_set, &block)
+      add_rule(rule_set)
+      within_scope(rule_set, &block)
+    end
+
+    # Runs the block with another current scope
+    #
+    # @param scope [Object] The scope for the block
+    # @yield Block evaluated in the class context
+    # @return [void]
+    def within_scope(scope, &block)
+      previous_scope = current_scope
+      @current_scope = scope
+
+      instance_exec(&block)
+    ensure
+      @current_scope = previous_scope
+    end
+  end
+end

data/lib/verquest/base/private_class_methods.rb

@@ -48,7 +48,7 @@ module Verquest
     # @yield Block defining the version's structure and properties
     # @return [void]
     def version(name, inherit: true, exclude_properties: [], &block)
-      version = Version.new(name:)
+      version = Version.new(name:, location:)
       versions.add(version)
 
       if inherit && @current_scope
@@ -125,8 +125,9 @@ module Verquest
     # @param required [Boolean, Array<Symbol>] Whether the field is required
     # @param nullable [Boolean] Whether the field can be null
     # @param schema_options [Hash] Additional schema options for the field
+    # @param parameter_examples [Hash, nil] Named OpenAPI Example Objects for the query parameter (query requests only)
     # @return [void]
-    def field(name, type: nil, map: nil, required: nil, nullable: nil, **schema_options)
+    def field(name, type: nil, map: nil, required: nil, nullable: nil, parameter_examples: nil, **schema_options)
       camelize(schema_options)
 
       type = default_options.fetch(:type, type)
@@ -135,7 +136,7 @@ module Verquest
       schema_options = default_options.except(:type, :required, :nullable).merge(schema_options)
 
       field = Properties::Field.new(name:, type:, map:, required:, nullable:, **schema_options)
-      current_scope.add(field)
+      add_property(field, parameter_examples)
     end
 
     # Defines a new enum property for the current version scope
@@ -146,8 +147,9 @@ module Verquest
     # @param required [Boolean, Array<Symbol>] Whether the enum is required
     # @param nullable [Boolean] Whether the enum can be null
     # @param schema_options [Hash] Additional schema options for the enum
+    # @param parameter_examples [Hash, nil] Named OpenAPI Example Objects for the query parameter (query requests only)
     # @return [void]
-    def enum(name, values:, map: nil, required: nil, nullable: nil, **schema_options)
+    def enum(name, values:, map: nil, required: nil, nullable: nil, parameter_examples: nil, **schema_options)
       camelize(schema_options)
 
       required = default_options.fetch(:required, false) if required.nil?
@@ -155,7 +157,7 @@ module Verquest
       schema_options = default_options.except(:required, :nullable).merge(schema_options)
 
       enum_property = Properties::Enum.new(name:, values:, map:, required:, nullable:, **schema_options)
-      current_scope.add(enum_property)
+      add_property(enum_property, parameter_examples)
     end
 
     # Defines a new constant property for the current version scope
@@ -166,14 +168,15 @@ module Verquest
     # @param required [Boolean, Array<Symbol>] Whether the constant is required
     # @param nullable [Boolean] Whether the constant can be null
     # @param schema_options [Hash] Additional schema options for the constant
+    # @param parameter_examples [Hash, nil] Named OpenAPI Example Objects for the query parameter (query requests only)
     # @return [void]
-    def const(name, value:, map: nil, required: nil, nullable: nil, **schema_options)
+    def const(name, value:, map: nil, required: nil, nullable: nil, parameter_examples: nil, **schema_options)
       camelize(schema_options)
       required = default_options.fetch(:required, false) if required.nil?
       nullable = default_options.fetch(:nullable, false) if nullable.nil?
 
       const = Properties::Const.new(name:, value:, map:, required:, nullable:, **schema_options)
-      current_scope.add(const)
+      add_property(const, parameter_examples)
     end
 
     # Defines a new object for the current version scope
@@ -183,9 +186,10 @@ module Verquest
     # @param required [Boolean, Array<Symbol>] Whether the object is required
     # @param nullable [Boolean] Whether the object can be null
     # @param schema_options [Hash] Additional schema options for the object
+    # @param parameter_examples [Hash, nil] Named OpenAPI Example Objects for the query parameter (query requests only)
     # @yield Block executed in the context of the new object definition
     # @return [void]
-    def object(name, map: nil, required: nil, nullable: nil, **schema_options, &block)
+    def object(name, map: nil, required: nil, nullable: nil, parameter_examples: nil, **schema_options, &block)
       unless block_given?
         raise ArgumentError, "a block must be given to define the object"
       end
@@ -196,7 +200,7 @@ module Verquest
       schema_options = default_options.except(:type, :required, :nullable).merge(schema_options)
 
       object = Properties::Object.new(name:, map:, required:, nullable:, **schema_options)
-      current_scope.add(object)
+      add_property(object, parameter_examples)
 
       if block_given?
         previous_scope = current_scope
@@ -251,13 +255,14 @@ module Verquest
     # @param map [String, nil] An optional mapping to another reference
     # @param required [Boolean, Array<Symbol>] Whether the reference is required
     # @param nullable [Boolean] Whether this reference can be null
+    # @param parameter_examples [Hash, nil] Named OpenAPI Example Objects for the query parameter (query requests only)
     # @return [void]
-    def reference(name, from:, property: nil, map: nil, required: nil, nullable: nil)
+    def reference(name, from:, property: nil, map: nil, required: nil, nullable: nil, parameter_examples: nil)
       required = default_options.fetch(:required, false) if required.nil?
       nullable = default_options.fetch(:nullable, false) if nullable.nil?
 
       reference = Properties::Reference.new(name:, from:, property:, map:, required:, nullable:)
-      current_scope.add(reference)
+      add_property(reference, parameter_examples)
     end
 
     # Defines a new array property for the current version scope
@@ -267,10 +272,12 @@ module Verquest
     # @param required [Boolean, Array<Symbol>] Whether the array property is required
     # @param nullable [Boolean] Whether this array can be null
     # @param map [String, nil] An optional mapping to another array property
+    # @param explode [Boolean, nil] In query requests, whether items are sent as repeated keys (true) or comma-separated (false); nil uses the configuration
     # @param item_schema_options [Hash] Additional JSON schema options for the array items (merged with custom type options)
     # @param schema_options [Hash] Additional schema options for the array property
+    # @param parameter_examples [Hash, nil] Named OpenAPI Example Objects for the query parameter (query requests only)
     # @return [void]
-    def array(name, type:, required: nil, nullable: nil, map: nil, item_schema_options: {}, **schema_options)
+    def array(name, type:, required: nil, nullable: nil, map: nil, explode: nil, parameter_examples: nil, item_schema_options: {}, **schema_options)
       camelize(schema_options)
 
       type = default_options.fetch(:type, type)
@@ -278,8 +285,8 @@ module Verquest
       nullable = default_options.fetch(:nullable, false) if nullable.nil?
       schema_options = default_options.except(:type, :required, :nullable).merge(schema_options)
 
-      array = Properties::Array.new(name:, type:, required:, nullable:, map:, item_schema_options:, **schema_options)
-      current_scope.add(array)
+      array = Properties::Array.new(name:, type:, required:, nullable:, map:, explode:, item_schema_options:, **schema_options)
+      add_property(array, parameter_examples)
     end
 
     # Defines a oneOf property for polymorphic schemas
@@ -312,6 +319,16 @@ module Verquest
       @current_scope = previous_scope if block_given?
     end
 
+    # Adds a property to the current scope
+    #
+    # @param property [Verquest::Properties::Base] The property to add
+    # @param parameter_examples [Hash, nil] Named OpenAPI Example Objects for the query parameter
+    # @return [void]
+    def add_property(property, parameter_examples)
+      property.parameter_examples = parameter_examples
+      current_scope.add(property)
+    end
+
     # Excludes specified properties from the current scope by removing them
     # from the version's property set
     #

data/lib/verquest/base/public_class_methods.rb

@@ -6,6 +6,9 @@ module Verquest
   # This module contains class methods that handle parameter mapping, schema generation,
   # and validation functionality for Verquest API request objects.
   module Base::PublicClassMethods
+    # Where request params can come from
+    LOCATIONS = %i[body query path].freeze
+
     # Maps incoming parameters to the appropriate structure based on version mapping
     #
     # @param params [Hash] The parameters to be mapped
@@ -22,7 +25,8 @@ module Verquest
 
       params = params.dup
       params = params.to_unsafe_h if params.respond_to?(:to_unsafe_h)
-      params = params.slice(*version_class.properties.keys) if remove_extra_root_keys && !version_class.combination?
+      params = params.slice(*version_class.all_properties.keys) if remove_extra_root_keys && !version_class.combination?
+      params = version_class.coerce_params(params)
 
       if validate && (validation_result = version_class.validate_params(params: params)) && validation_result.any?
         case Verquest.configuration.validation_error_handling
@@ -52,6 +56,52 @@ module Verquest
       end
     end
 
+    # Sets or returns where the request's params come from
+    #
+    # A query request (`location :query`) or path request (`location :path`)
+    # converts strings to the types its schema expects before validating them,
+    # and documents its properties with {#to_parameters}. Subclasses inherit
+    # the location.
+    #
+    # @example
+    #   class ListQuery < Verquest::Base
+    #     location :query
+    #
+    #     version "2025-06" do
+    #       field :page, type: :integer
+    #     end
+    #   end
+    #
+    # @param value [Symbol, nil] `:body`, `:query` or `:path` to set the location, nil to return it
+    # @return [Symbol] The location, `:body` unless set on this class or a superclass
+    # @raise [ArgumentError] If the value is not a known location, or a version is already defined
+    def location(value = nil)
+      return @location || (superclass.respond_to?(:location) ? superclass.location : :body) if value.nil?
+
+      raise ArgumentError, "Location must be one of #{LOCATIONS.join(", ")}" unless LOCATIONS.include?(value)
+      raise ArgumentError, "Location must be set before the first version" if current_scope
+
+      @location = value
+    end
+
+    # Returns OpenAPI parameter objects for a query or path request
+    #
+    # One parameter per property, with symbol keys, ready for rswag's `parameter`.
+    # Schemas are inlined, arrays get `style: :form` and their explode value, and
+    # objects get `style: :deepObject`.
+    #
+    # @example
+    #   ListQuery.to_parameters(version: "2025-06").each { |p| parameter(p) }
+    #
+    # @param version [String, nil] Specific version to use, defaults to configuration setting
+    # @return [Array<Hash>] The OpenAPI parameter objects
+    # @raise [ArgumentError] If the request is a body request
+    def to_parameters(version: nil)
+      raise ArgumentError, "#{name} has no parameters (location #{location.inspect})" if location == :body
+
+      resolve(version).parameters
+    end
+
     # Returns the JSON schema for the request
     #
     # @param version [String, nil] Specific version to use, defaults to configuration setting

data/lib/verquest/base.rb

@@ -33,6 +33,7 @@ module Verquest
   class Base
     extend Base::HelperClassMethods
     extend Base::PrivateClassMethods
+    extend Base::ConditionClassMethods
     extend Base::PublicClassMethods
   end
 end