verquest 0.6.4 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5be764c988f4ea26a04112ed68684fcc7d292e25c37c6c2105f1c62ba7c92bc8
-  data.tar.gz: 15cead4ea24fc972317e15157fd14194098f2f543ae7d2402ae81a443ad198d9
+  metadata.gz: 8bc88f55be50f80f099c989c617954b1600ed5d61adfcf35fccd430fbbce21cc
+  data.tar.gz: 8741893b6b9c3d5e91db1b6d6c3e3bf72e84ac43babd34f62a04859ee5bf6a7e
 SHA512:
-  metadata.gz: 898d20e10c9ea20ccacd10fb8711778444f7cc096c09152e6ba48a167e363a19e60a2d8ed481205d2331b3b5a076ccc888a279ba44121342e698ade944ff9c8b
-  data.tar.gz: 23dba503f13f33a571f65008eaa13f2f94347dd974cfa45e9e8bb2f76e9e2599e0ab19fed299b2ea43144641e642c54a30d636ffe0d332967cb7ec84c521f3d6
+  metadata.gz: d77a640d8afade1d2578899ef72a39550d870452f16e81bfef9c2aa61506c1b09aea07e7f23b3ef35ccc38218295c620389c1cda3e6eb9cdf1bb3227638358b1
+  data.tar.gz: 308cdf6806df22ec89108911cfe9a6e351e9b9c3c7b925a8a15dd31c108adc19f51d8f361528ecd566e057042b1382603ec6b3652e4f9604a5e45c711e7d3d81

data/CHANGELOG.md

@@ -1,6 +1,48 @@
 ## [Unreleased]
 
-## [0.6.3] - 2026-09-23
+## [0.7.0] - 2026-11-05
+
+### Added
+- Query parameters: `location :query` on a request class converts query strings to the types its schema expects (numbers, booleans, null, comma-separated or repeated arrays, one level of `deepObject`) before `process` validates and maps them. `to_parameters(version:)` returns OpenAPI parameter objects with symbol keys for rswag. Arrays take `explode:`, defaulting to the new `config.query_array_explode` (`true`). `parameter_examples:` on `field`, `enum`, `const`, `array`, `object` and `reference` adds named OpenAPI examples to the parameter without putting them in the JSON schemas. Shapes query strings can't express raise the new `Verquest::DefinitionError` when the version is defined.
+- Path parameters: `location :path` converts and validates path params like query params, and `to_parameters` documents them as `in: :path`. Properties must be required scalars, otherwise the version raises `Verquest::DefinitionError`.
+- Conditional schemas: `condition` with `given`, `then_apply` and `else_apply` compiles to JSON Schema `if` / `then` / `else` in a version, an `object` or an inline `collection`. Rules: `present`, `absent`, `equals`, `value_in`, `satisfies`, `any` and `none`. Branch properties are listed in the scope's `properties` (so `additionalProperties: false` keeps working and the mapping stays flat), and each branch forbids the properties only the other branch declares, which gives one validation error per problem. Also adds the `depends_on` shorthand and `exclude_conditions` for later versions. Conditions need `json_schema_version` `:draft7` or later, or `:openapi31`; other versions raise `ArgumentError`.
+- [Rails and rswag guide](docs/rails.md): a controller concern for body, query and path classes, and an rswag shared context.
+- `condition ..., document_as: :one_of` documents a condition in a version as a `oneOf` of its branches in `to_schema`, while the validation schema keeps `if` / `then` / `else`. `then_apply` and `else_apply` take `title`, `description` and `deprecated` for their variant.
+
+### Changed
+- A `one_of` with a `discriminator:` keeps the discriminator in the validation schema. Its variants move into local `definitions` referenced by `$ref`, under a content-hash id written as both `$id` and `id` (`https://verquest.local/one_of/...`). With `json_schema_version = :openapi31` or `:openapi30`, validation errors come only from the variant the discriminator selects, and a missing, unknown or non-object value gets a single `discriminator` error. Under `:openapi30`, valid payloads that were rejected with `oneOf` errors (OpenAPI 3.0 has no `const`, so they matched every variant) now pass. Other versions validate as before, but `to_validation_schema` output changes. If you register these schemas with another validator, note the new ids.
+- The transformer builds one plan at initialization and is frozen. `Verquest::NOT_FOUND` moved to `Verquest::Transformer::Path::NOT_FOUND`. In the mapping, `_variant_path` and `_nullable_path` hold the full source path inside collections too (`entries[]/content` instead of `content`).
+- A `null` oneOf maps to `null` whether it has a discriminator or not, and inside multiple oneOfs.
+- A oneOf inside a `collection` is listed in the mapping's `_oneOfs` array, like several oneOfs, instead of putting its metadata at the top level.
+- A oneOf variant property moved out of a collection item with `map: "/..."` raises `Verquest::MappingError` when the class is defined. Each item selects its own variant, so it can't be collected outside the items.
+- The transformer allocates two to four times fewer objects per call and runs 15–40% faster. `rake bench` measures it.
+- A version compiles its validation schema once per configuration instead of on every `process`, which makes `process` with validation up to 4 times faster.
+- Under `json_schema_version` `:draft4` and `:openapi30`, which have no `const`, a `const` property is written as a one-value `enum` in `to_schema` and `to_validation_schema`, so it is enforced.
+- An unnamed `one_of` next to other properties raises `ArgumentError` when it is declared. It was dropped from the schema.
+- Versions build their transformer from their properties instead of from their `mapping` hash, so the transformer no longer depends on the mapping's metadata keys.
+
+### Deprecated
+- `Verquest::Transformer.new(mapping:, discriminator:)`. Use `MyRequest.process`, or `MyRequest.resolve(version).transformer`; versions build their transformer from their properties, and the mapping constructor will be removed in 1.0.0. It warns when deprecation warnings are on (`Warning[:deprecated] = true` or `ruby -W:deprecated`), which Ruby leaves off by default.
+
+### Fixed
+- A `one_of` inside an `object` mapped a valid payload to an empty hash, and two of them clashed. It also works inside an object in a collection.
+- Empty collection items are kept (they were dropped, or became `nil` before a later item), and a `null` nested object inside an item stays `null`.
+- A `null` nullable oneOf with a nested `map:` (e.g. `"billing/payment"`) is written as a nested key, not as the literal key `"billing/payment"`.
+- A collection item without its optional oneOf, or with a `null` nullable one, no longer raises "No matching schema found". A nullable oneOf without a discriminator in a collection can be defined (the duplicate-mapping check counted its metadata).
+- Properties whose names start with `_` are mapped next to oneOfs and inverted in `external_mapping`.
+- A collection with `map:` and a oneOf no longer nests every item under the collection name again, also when a variant's first property is moved out with `map: "/..."`.
+- Without validation, a present oneOf without its discriminator raises "Missing discriminator" instead of mapping to an empty hash, and an unknown value raises in collection items too. A value naming a metadata key no longer crashes with `NoMethodError`.
+- Variant inference (a oneOf without a discriminator) reads the variant schemas in the configured `json_schema_version`. Under draft 4, a boolean `exclusive_maximum` crashed it. Under draft 4 and OpenAPI 3.0, which have no `const`, it reads `const` as a one-value `enum`, so variants that differ only by a const are still told apart.
+- oneOfs in a collection inside a collection, and in several collections of one version, are mapped. Before, the discriminator read an array of values, and the second collection's oneOf overwrote the first one's.
+- A property moved out of collection items with `map: "/..."` writes `null` for items without the value, instead of an internal object. In a collection holding a oneOf, it is collected outside the items again.
+- `external_mapping` inverts the oneOfs nested in objects and collections, which were left as a hash key.
+- A `reference`, or a `collection` with `item:`, to a request holding a oneOf no longer drops its data.
+- A oneOf inside a oneOf variant, inline or referenced, maps its data, and so does a collection of oneOfs inside a variant. The data was dropped. In `mapping` and `external_mapping`, such a nested oneOf is listed in the variant's `_oneOfs` array, where it used to show up as prefixed metadata keys and stringified hashes.
+- In `mapping` and `external_mapping`, an absolute `map:` in a request used as a oneOf reference variant points to the root, as the transformer always mapped it. It was nested under the variant.
+- A `reference` with `property:` to an object, a collection or a oneOf maps its data. Only scalar properties worked.
+- A collection whose only property is a named `one_of` keeps the name in its item schema, so valid items pass validation.
+
+## [0.6.4] - 2026-09-23
 
 ### Fixed
 - Handling `nullable: true` ([#18](https://github.com/verquest/verquest/pull/18), [@CiTroNaK](https://github.com/CiTroNaK))

data/README.md

@@ -3,25 +3,33 @@
 [![Gem Version](https://badge.fury.io/rb/verquest.svg)](https://badge.fury.io/rb/verquest)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
 
-Verquest is a Ruby gem that offers an elegant solution for versioning API requests. It simplifies the process of defining and evolving your API schema over time, with robust support for:
+Verquest describes your API's requests (bodies, query strings and path parameters) with a small Ruby DSL, one definition per API version. From that definition you get:
 
-- Defining versioned request structures
-- Gracefully handling API versioning
-- Mapping between external and internal parameter structures
-- Validating parameters against [JSON Schema](https://json-schema.org/)
-- Generating components for OpenAPI documentation
-- Mapping error keys back to the external API structure
+- validation of incoming params against [JSON Schema](https://json-schema.org/), with errors that point at the invalid value (`/address/city`);
+- mapping from your public API structure to the structure your app uses (`full_name` → `name`);
+- JSON Schema components and OpenAPI parameters for your docs, ready for [rswag](https://github.com/rswag/rswag);
+- version resolution: ask for `2025-07` and get the closest earlier definition, so unchanged requests need no new version.
+
+It works in any Ruby app and has no Rails dependency. [Rails and rswag](docs/rails.md) shows how to plug it into controllers and request specs.
 
 Sponsored by [Stora](https://stora.co)
 
-> The gem is still in development. Until version 1.0, the API may change. There are some features like `oneOf`, `anyOf`, `allOf` that are not implemented yet. See open [issues](https://github.com/verquest/verquest/issues?q=sort:updated-desc%20is:issue%20is:open%20label:enhancement).
+> Verquest is not 1.0 yet, so minor releases can change the API; the [changelog](CHANGELOG.md) lists every change. `anyOf` and `allOf` aren't in the DSL yet, see the open [issues](https://github.com/verquest/verquest/issues?q=sort:updated-desc%20is:issue%20is:open%20label:enhancement).
+
+## Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Features](#core-features): [schema definition](#schema-definition-and-validation), [oneOf](#oneof), [conditional schemas](#conditional-schemas), [custom field types](#custom-field-types), [versioning](#versioning), [mapping](#mapping-request-structure), [query parameters](#query-parameters), [path parameters](#path-parameters), [OpenAPI components](#component-generation-for-openapi)
+- [Rails and rswag](docs/rails.md)
+- [Configuration](#configuration)
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "verquest", "~> 0.6"
+gem "verquest", "~> 0.7"
 ```
 
 And then execute:
@@ -32,9 +40,10 @@ bundle install
 
 ## Quick Start
 
-### Define a versioned API requests
+### Define a request
+
+A request class inherits from `Verquest::Base` and describes each version in a `version` block. An address, reused below:
 
-Address Create Request
 ```ruby
 class AddressCreateRequest < Verquest::Base
   description "Address Create Request"
@@ -49,9 +58,10 @@ class AddressCreateRequest < Verquest::Base
     end
   end
 end
-````
+```
+
+A user request that uses the address:
 
-User Create Request that uses the `AddressCreateRequest`
 ```ruby
 class UserCreateRequest < Verquest::Base
   description "User Create Request"
@@ -97,31 +107,32 @@ class UserCreateRequest < Verquest::Base
 end
 ```
 
-### Example usage in Rails Controller
+### Process params in a Rails controller
 
-```ruby
+`process` validates the params and returns them mapped to your internal structure. It takes `ActionController::Parameters` as they are, so it replaces strong parameters:
 
+```ruby
 class UsersController < ApplicationController
-  rescue_from Verquest::InvalidParamsError, with: :handle_invalid_params
-  
-  def create
-    result = Users::Create.call(params: user_params) # service object to handle the creation logic
-
-    if result.success?
-      # render success response
-    else
-      # render error response
-    end
+  rescue_from Verquest::InvalidParamsError do |error|
+    render json: {errors: error.errors}, status: :unprocessable_content
   end
 
-  private
-
-  def user_params
-    UserCreateRequest.process(params, version: params[:api_version])
+  def create
+    user = Users::Create.call(params: UserCreateRequest.process(params, version: params[:api_version]))
+    render json: user, status: :created
   end
 end
 ```
 
+Each error points at the invalid value:
+
+```ruby
+error.errors
+# => [{pointer: "/email", type: "format", message: "value at `/email` does not match format: email", details: nil}]
+```
+
+Set `config.current_version` to drop the `version:` argument, or `config.validation_error_handling = :result` to get a `Verquest::Result` instead of an exception (see [Configuration](#configuration)). For query and path parameters in controllers, see [Rails and rswag](docs/rails.md).
+
 ### JSON schema for OpenAPI
 You can generate JSON Schema for your versioned requests, which can be used for API documentation:
 
@@ -268,19 +279,22 @@ The JSON schema can be used for both validation of incoming parameters and for g
 
 #### Component types
 
-- `field`: Represents a scalar value (string, integer, boolean, etc.).
-- `enum`: Represents a property with a limited set of values (enumeration).
-- `object`: Represents a JSON object with properties.
-- `array`: Represents a JSON array with scalar items.
-- `collection`: Represents a array of objects defined manually or by a reference to another request.
-- `reference`: Represents a reference to another request, allowing you to reuse existing request structures.
-- `const`: Represents a [constant](https://json-schema.org/understanding-json-schema/reference/const#constant-values) value that is always present in the request.
+- `field`: a scalar value (string, integer, boolean, etc.).
+- `enum`: a value from a fixed list.
+- `object`: a JSON object with its own properties.
+- `array`: a JSON array of scalar items.
+- `collection`: a JSON array of objects, defined inline or with `item:` pointing at another request.
+- `reference`: another request reused in place, or one of its properties with `property:`.
+- `const`: a [constant](https://json-schema.org/understanding-json-schema/reference/const#constant-values) value.
+- `one_of`: exactly one of several request shapes, see [oneOf](#oneof).
 
 #### Helper methods
 
-- `description`: Adds a description to the request or per version.
-- `schema_options`: Allows you to set additional options for the JSON Schema, such as `additional_properties` for request or per version. All fields (except `reference`) can be defined with options like `required`, `format`, `min_lenght`, `max_length`, etc. all in snake case.
-- `with_options`: Allows you to define multiple fields with the same options, reducing repetition.
+- `description`: a description for the request, or for one version.
+- `schema_options`: extra JSON Schema keywords for the request or one version, such as `additional_properties: false`.
+- `with_options`: shared options for every property in the block.
+
+Properties (except `reference`) take JSON Schema keywords in snake case, such as `format`, `min_length` or `max_length`, and Verquest writes them in camel case (`minLength`).
 
 #### Required properties
 
@@ -396,6 +410,166 @@ Will produce this validation schema:
 }
 ```
 
+#### Conditional schemas
+
+Use `condition` when a request changes shape depending on the payload. It compiles to JSON Schema `if` / `then` / `else` and works in a version, an `object`, and an inline `collection`:
+
+```ruby
+version "2025-09" do
+  field :effective_from, type: :string, required: true
+  field :credit_card, type: :string
+  field :billing_address, type: :string
+
+  condition :pricing do
+    given { present :percentages }
+    then_apply do
+      object :percentages, required: true, min_properties: 1 do
+        field :unit_types, type: :number, maximum: 9999.99
+      end
+    end
+    else_apply do
+      field :percentage, type: :number, required: true, deprecated: true, not: {const: 0}
+      object :applies_to, deprecated: true do
+        field :unit_types, type: :boolean, map: "/apply_to_unit_types"
+      end
+    end
+  end
+
+  depends_on :credit_card do # condition { given { present :credit_card }; then_apply { ... } }
+    present :billing_address
+  end
+end
+```
+
+- `given` (the `if`) holds rules only. `then_apply` and `else_apply` hold rules and property declarations. A condition needs `given` and at least one branch.
+- Rules: `present :a, :b`, `absent :a`, `equals :kind, "company"`, `value_in :kind, %w[a b]`, `satisfies :age, minimum: 18`, `any { ... }` and `none { ... }`. Rules in one block must all hold. Inside `given`, `equals`, `value_in` and `satisfies` also require their property.
+- Branch properties are listed in the scope's `properties`, so `additionalProperties: false` keeps working and the mapping is the flat union. Each branch gets only rules: its required names, and `false` for properties that only the other branch declares. A missing branch is generated.
+- Several conditions on one scope go into `allOf`, one entry each.
+- `exclude_conditions :pricing` removes an inherited named condition in a later version. A named condition can be declared only once per scope, so exclude an inherited one before redeclaring it.
+- `exclude_properties` only sees regular properties. To drop a branch property, exclude its condition.
+- Conditions need `json_schema_version` `:draft7` or later, or `:openapi31`. Other versions ignore `if` / `then` / `else`, so Verquest raises `ArgumentError` when the version is prepared.
+
+The example gives this schema:
+
+```json
+{
+  "type": "object",
+  "required": ["effective_from"],
+  "properties": {
+    "effective_from": {"type": "string"}, "credit_card": {"type": "string"}, "billing_address": {"type": "string"},
+    "percentages": {"...": "..."}, "percentage": {"...": "..."}, "applies_to": {"...": "..."}
+  },
+  "additionalProperties": false,
+  "allOf": [
+    {
+      "if": {"required": ["percentages"]},
+      "then": {"required": ["percentages"], "properties": {"percentage": false, "applies_to": false}},
+      "else": {"required": ["percentage"], "properties": {"percentages": false}}
+    },
+    {"if": {"required": ["credit_card"]}, "then": {"required": ["billing_address"]}}
+  ]
+}
+```
+
+##### Documenting a condition as a oneOf
+
+`document_as: :one_of` keeps `if` / `then` / `else` in the validation schema, but `to_schema` (the documentation) renders a `oneOf` with one variant per branch. `then_apply` and `else_apply` take a `title`, `description` and `deprecated` for their variant:
+
+```ruby
+version "2025-09" do
+  field :effective_from, type: :string, required: true
+
+  condition :pricing, document_as: :one_of do
+    given { present :percentages }
+    then_apply title: "Per-type percentages" do
+      object :percentages, required: true, min_properties: 1 do
+        field :unit_types, type: :number, maximum: 9999.99
+      end
+    end
+    else_apply title: "Shared percentage", deprecated: true do
+      field :percentage, type: :number, required: true
+    end
+  end
+end
+```
+
+```json
+{
+  "oneOf": [
+    {"type": "object", "title": "Per-type percentages", "required": ["effective_from", "percentages"], "properties": {"effective_from": {"...": "..."}, "percentages": {"...": "..."}}, "additionalProperties": false},
+    {"type": "object", "title": "Shared percentage", "deprecated": true, "required": ["effective_from", "percentage"], "properties": {"effective_from": {"...": "..."}, "percentage": {"...": "..."}}, "additionalProperties": false}
+  ]
+}
+```
+
+- Each variant lists the version's properties without the ones only the other branch declares, and adds its branch's rules. The `then` variant also holds the `given` rules, and the `else` variant `not` the `given` rules, unless it already forbids a property `given` requires. Both schemas accept the same payloads. When a rule clashes with a property's own schema (for example `given { absent :note }` against a declared `note`, or `satisfies :age, minimum: 18` against `minimum: 0`), the variant keeps both by adding the rule under `allOf`.
+- Validation still uses the `if` / `then` / `else` schema, so validation errors point at those rules, not at a `oneOf` variant.
+- When `additionalProperties` isn't `false`, the other branch's properties are forbidden with `false` in each variant.
+- Only for a condition in a version, and it must be the only condition in that version. The version's `description` stays at the root of the schema.
+- The schema has no root `properties`, so `to_ref(property:)` can't point into it.
+
+#### oneOf
+
+`one_of` accepts exactly one of several shapes. Each variant is a `reference` to another request, and `discriminator:` names the property that tells them apart:
+
+```ruby
+class CardPaymentComponent < Verquest::Base
+  version "2025-06" do
+    const :method, value: "card", required: true
+    field :card_number, type: :string, required: true
+    field :expiry, type: :string, required: true
+  end
+end
+
+class OrderRequest < Verquest::Base
+  version "2025-06" do
+    field :order_id, type: :string, required: true
+
+    one_of name: :payment, discriminator: :method, required: true do
+      reference :card, from: CardPaymentComponent
+      reference :bank, from: BankPaymentComponent
+    end
+  end
+end
+
+OrderRequest.process({"order_id" => "o1", "payment" => {"method" => "card", "card_number" => "4242", "expiry" => "12/30"}})
+# => {"order_id" => "o1", "payment" => {"method" => "card", "card_number" => "4242", "expiry" => "12/30"}}
+```
+
+`to_schema` documents it as an OpenAPI `oneOf` with a `discriminator` mapping to the variants' components:
+
+```ruby
+{"oneOf" => [{"$ref" => "#/components/schemas/CardPaymentComponent"}, {"$ref" => "#/components/schemas/BankPaymentComponent"}],
+ "discriminator" => {"propertyName" => "method", "mapping" => {"card" => "#/components/schemas/CardPaymentComponent", "bank" => "#/components/schemas/BankPaymentComponent"}}}
+```
+
+- Without `name:`, the whole request is one of the variants (`one_of discriminator: :type do ... end` as the only property of a version).
+- Without `discriminator:`, the value must match exactly one variant's schema. Validation rejects it otherwise; with validation off, mapping raises `Verquest::MappingError`.
+- `one_of` works inside objects, collections and other variants, and with `nullable: true` and `map:`.
+
+#### oneOf discriminators in validation
+
+A `one_of` with a `discriminator:` keeps the discriminator in the validation schema. Its variants move into local `definitions` that `oneOf` references with `$ref`. An id, written as both `$id` and `id` so every JSON Schema version reads it, makes those references resolve wherever the schema is embedded:
+
+```ruby
+one_of name: :pet, discriminator: :type do
+  reference :dog, from: DogComponent
+  reference :cat, from: CatComponent
+end
+```
+
+```json
+{
+  "$id": "https://verquest.local/one_of/3f1c9a0b2d4e5f67",
+  "id": "https://verquest.local/one_of/3f1c9a0b2d4e5f67",
+  "definitions": {"dog": {"type": "object", "...": "..."}, "cat": {"type": "object", "...": "..."}},
+  "oneOf": [{"$ref": "#/definitions/dog"}, {"$ref": "#/definitions/cat"}],
+  "discriminator": {"propertyName": "type", "mapping": {"dog": "#/definitions/dog", "cat": "#/definitions/cat"}}
+}
+```
+
+With `json_schema_version = :openapi31` or `:openapi30`, the validator checks only the variant the discriminator selects, so validation errors come from that variant only. A value that isn't an object, or that has no known discriminator value, gets a single `discriminator` error. Other versions ignore `discriminator` and check every variant.
+
 #### Custom Field Types
 
 You can define custom field types that can be used in `field` and `array` in the configuration.
@@ -559,7 +733,7 @@ Will be transformed to:
   "address_city": "Springfield",
   "address_zip": "12345"
 }
-````
+```
 
 What you can use:
 - `/` to reference the root of the request structure
@@ -585,9 +759,81 @@ Will produce the following mapping:
 }
 ```
 
-There are some limitations and the implementation can be improved, but it should works for most common use cases.
+The mapping tests in [`test/verquest/base_test.rb`](test/verquest/base_test.rb) have more examples.
+
+### Query parameters
+
+A request class with `location :query` describes query parameters. `process` converts the query strings to the types the schema expects before it validates and maps them, and `to_parameters` documents them as OpenAPI parameters.
+
+```ruby
+class DealsIndexQuery < Verquest::Base
+  location :query # inherited, so it can be set once on a base class
 
-See the mapping test (in `test/verquest/base_test.rb`) for more examples of mapping.
+  version "2025-06" do
+    field :page, type: :integer, minimum: 1, default: 1
+    field :archived, type: :boolean
+    enum :sort_direction, values: %w[ASC DESC], default: "DESC"
+    array :status, type: :string, explode: false, item_schema_options: {enum: %w[open won lost]}
+
+    object :created do # sent as created[after]=...
+      field :after, type: :string, format: "date-time", map: "/created_after"
+    end
+  end
+end
+
+DealsIndexQuery.process(request.query_parameters, version: "2025-06")
+# ?page=2&archived=true&status=open,won&created[after]=2025-01-01T00:00:00Z
+# => {"page" => 2, "archived" => true, "sort_direction" => "DESC", "status" => ["open", "won"], "created_after" => "2025-01-01T00:00:00Z"}
+```
+
+Conversion follows the validation schema:
+- `integer` and `number` from digits (`"2"`, `"-1.5"`), `boolean` from `"true"` and `"false"`, `null` from an empty string when the schema allows it;
+- arrays split on commas with `explode: false` (`status=open,won`), or come from repeated keys with `explode: true` (`status[]=open&status[]=won`; Rails keeps only the last value of a plain repeated key). `config.query_array_explode` sets the default (`true`);
+- objects (`deepObject`, one level deep) convert each property.
+
+A value that can't be converted is left as it is, so the validation reports it. Shapes a query string can't express (`one_of` properties, arrays of objects, objects inside objects) raise `Verquest::DefinitionError` when the version is defined.
+
+`to_parameters` returns one parameter object per property, with symbol keys and the schema inlined, ready for rswag:
+
+```ruby
+DealsIndexQuery.to_parameters(version: "2025-06").each { |p| parameter(p) }
+# {name: "status", in: :query, required: false, style: :form, explode: false,
+#  schema: {type: "array", items: {type: "string", enum: ["open", "won", "lost"]}}}
+```
+
+Named OpenAPI examples go on the parameter with `parameter_examples:`. They are left out of the JSON schemas, because JSON Schema `examples` is an array:
+
+```ruby
+array :status, type: :string, explode: false, item_schema_options: {enum: %w[open won lost]},
+  parameter_examples: {single: {value: %w[open]}, multiple: {value: %w[open won]}}
+# => {name: "status", ..., examples: {single: {value: ["open"]}, multiple: {value: ["open", "won"]}}, schema: {...}}
+```
+
+A property reference to another query class reuses its definition, e.g. a shared `expand` parameter: `reference :expand, from: ExpandQuery, property: :expand`.
+
+### Path parameters
+
+`location :path` works like `location :query`, but documents `in: :path` parameters. Path parameters must be required scalars; arrays, objects, one_of and optional properties raise `Verquest::DefinitionError`.
+
+```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
+
+DealPath.process({"id" => params[:id]}) # raises Verquest::InvalidParamsError for "con_123"
+DealPath.to_parameters(version: "2025-06")
+# => [{name: "id", in: :path, required: true, description: "The ID of the deal", schema: {type: "string", pattern: "^deal_"}}]
+```
+
+The parameter name comes from the property. When a route uses another name (`/deals/{deal_id}/win`), rename the key before `process` and the `name` of the parameter object, as the [Rails and rswag](docs/rails.md) example does.
+
+### Rails and rswag
+
+See [Rails and rswag](docs/rails.md) for a controller concern that processes body, query and path classes, and an rswag shared context that documents them.
 
 ### Component Generation for OpenAPI
 
@@ -621,20 +867,28 @@ Verquest.configure do |config|
   config.remove_extra_root_keys = true # default
   
   # Set custom version resolver
-  config.version_resolver = CustomeVersionResolver # default is `Verquest::VersionResolver`
+  config.version_resolver = CustomVersionResolver # default is `Verquest::VersionResolver`
   
   # Set default value for additional properties
   config.default_additional_properties = false # default
+
+  # Default explode value of query arrays (true: status[]=a&status[]=b, false: status=a,b)
+  config.query_array_explode = true # default
+
+  # Reusable field types, see Custom Field Types
+  config.custom_field_types = {} # default
 end
 ```
 
 ## Documentation
 
-For detailed documentation, please visit the [YARD documentation](https://www.rubydoc.info/gems/verquest/0.6.0/).
+The API reference is on [RubyDoc](https://www.rubydoc.info/gems/verquest). Guides:
+
+- [Rails and rswag](docs/rails.md): controllers and request specs for body, query and path parameters.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. `bundle exec rake` runs the tests, RuboCop and the YARD documentation check; `COVERAGE=1 bundle exec rake` adds a coverage report. `bin/console` opens an interactive prompt with the gem loaded.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `gem_version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/Rakefile

@@ -32,4 +32,9 @@ task :yard do
   puts "\nYARD documentation: 100% documented"
 end
 
+desc "Benchmark the transformer (objects allocated and calls per second)"
+task :bench do
+  ruby "-Ilib", "bench/transformer.rb"
+end
+
 task default: %i[test rubocop yard]