rspec-openapi 0.25.1 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fdb09465b214320cfd32bf020363827d17c3346d48cb7e724effc99df6bdf722
-  data.tar.gz: 9947b0df4b2af301473ff89cd52cd035d8a4cb129bd83f8aacef2fc4df107cd5
+  metadata.gz: 254e5e91a3965a417ad69c8b61d4bfdde6af42ab7aba14854d5531d73f4a793d
+  data.tar.gz: 3fa43709cf02b95bb1f4815eb4eebefde3ad5e5e2aabf0439267dce2c06cba36
 SHA512:
-  metadata.gz: f17329553b8d2a02b196faba4ac592826557acb79648f364994614759e762608241d1310be6080873703af3b7f45d111db3509302f9ec22270c6c3c849bbd180
-  data.tar.gz: dd616bc6570e99d2b6439d4003bcadcdc9881613c6f4ba0428191ceef2c7c73dd185c5e385ea6c8af271f98d5c67d3e597062052d2c3bd7c59d1c0f6e75f0deb
+  metadata.gz: 486180ee4a5b04de2f3539864e6f5be519ea262f0b30afc661377aa2da69c9c6fba883128ff02c006a9b073766848fc8b2ef5ad99cbb2fc55f8201de1a5975de
+  data.tar.gz: a074396a8847d7d9950fc414591e68da5c1def3121fdae896aa6e626e512c5860dc58b5be83248979bb6612628f224d367d066a8d5939991fbe98f8000626934

data/.github/workflows/create_release.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: 'Version to release (e.g. 0.25.2 or 0.26.0)'
+        description: 'Version to release (e.g. 0.26.1 or 0.27.0)'
         required: true
 
 jobs:

data/.github/workflows/publish.yml

@@ -39,7 +39,7 @@ jobs:
       - uses: rubygems/release-gem@v1
 
       - name: Create GitHub release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           tag_name: ${{ github.ref_name }}
           name: ${{ github.ref_name }}

data/.github/workflows/validate-openapi.yml

@@ -0,0 +1,21 @@
+name: validate-openapi
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+
+jobs:
+  redocly-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - run: npx --yes @redocly/cli@2.30.4 lint

data/.gitignore

@@ -14,3 +14,5 @@
 .rspec_status
 
 spec/apps/rails/log/
+
+/mise.toml

data/.rubocop_todo.yml

@@ -24,7 +24,7 @@ Metrics/CyclomaticComplexity:
 # Offense count: 22
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 36
+  Max: 37
 
 # Offense count: 5
 # Configuration parameters: AllowedMethods, AllowedPatterns.

data/README.md

@@ -1,6 +1,5 @@
 # rspec-openapi [![Gem Version](https://badge.fury.io/rb/rspec-openapi.svg)](https://rubygems.org/gems/rspec-openapi) [![test](https://github.com/exoego/rspec-openapi/actions/workflows/test.yml/badge.svg)](https://github.com/exoego/rspec-openapi/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/exoego/rspec-openapi/branch/master/graph/badge.svg?token=egYm6AlxkD)](https://codecov.io/gh/exoego/rspec-openapi) [![Ruby-toolbox](https://img.shields.io/badge/ruby-toolbox-a61414?cacheSeconds=31536000)](https://www.ruby-toolbox.com/projects/rspec-openapi) [![DeepWiki](https://img.shields.io/badge/See_on-DeepWiki-blue)](https://deepwiki.com/exoego/rspec-openapi)
 
-
 Generate OpenAPI schema from RSpec request specs.
 
 ## What's this?
@@ -8,7 +7,8 @@ Generate OpenAPI schema from RSpec request specs.
 There are some gems which generate OpenAPI specs from RSpec request specs.
 However, they require a special DSL specific to these gems, and we can't reuse existing request specs as they are.
 
-Unlike such [existing gems](#links), rspec-openapi can generate OpenAPI specs from request specs without requiring any special DSL.
+Unlike such [existing gems](#links), rspec-openapi can generate OpenAPI specs from request specs without requiring any
+special DSL.
 Furthermore, rspec-openapi keeps manual modifications when it merges automated changes to OpenAPI specs
 in case we can't generate everything from request specs.
 
@@ -30,7 +30,9 @@ $ OPENAPI=1 bundle exec rspec
 
 ### Example
 
-Let's say you have [a request spec](https://github.com/exoego/rspec-openapi/blob/24e5c567c2e90945c7a41f19f71634ac028cc314/spec/requests/rails_spec.rb#L38) like this:
+Let's say you
+have [a request spec](https://github.com/exoego/rspec-openapi/blob/24e5c567c2e90945c7a41f19f71634ac028cc314/spec/requests/rails_spec.rb#L38)
+like this:
 
 ```rb
 RSpec.describe 'Tables', type: :request do
@@ -67,18 +69,18 @@ paths:
     get:
       summary: index
       tags:
-      - Table
+        - Table
       parameters:
-      - name: page
-        in: query
-        schema:
-          type: integer
-        example: 1
-      - name: per
-        in: query
-        schema:
-          type: integer
-        example: 10
+        - name: page
+          in: query
+          schema:
+            type: integer
+          example: 1
+        - name: per
+          in: query
+          schema:
+            type: integer
+          example: 10
       responses:
         '200':
           description: returns a list of tables
@@ -96,11 +98,11 @@ paths:
                     # ...
 ```
 
-and the schema file can be used as an input of [Swagger UI](https://github.com/swagger-api/swagger-ui) or [Redoc](https://github.com/Redocly/redoc).
+and the schema file can be used as an input of [Swagger UI](https://github.com/swagger-api/swagger-ui)
+or [Redoc](https://github.com/Redocly/redoc).
 
 ![Redoc example](./spec/apps/rails/doc/screenshot.png)
 
-
 ### Configuration
 
 The following configurations are optional.
@@ -251,7 +253,8 @@ paths:
 # Note) #/components/schemas is not needed to be defined.
 ```
 
-3. Then, re-run rspec-openapi. It will generate `#/components/schemas` with the referenced schema (`User` for example) newly-generated or updated.
+3. Then, re-run rspec-openapi. It will generate `#/components/schemas` with the referenced schema (`User` for example)
+   newly-generated or updated.
 
 ```yaml
 paths:
@@ -354,21 +357,22 @@ Some examples' attributes can be overwritten via RSpec metadata options. Example
 
 ```rb
   describe 'GET /api/v1/posts', openapi: {
-    summary: 'list all posts',
-    description: 'list all posts ordered by pub_date',
-    tags: %w[v1 posts],
-    required_request_params: %w[limit],
-    security: [{"MyToken" => []}],
-  } do
-    # ...
-  end
+  summary: 'list all posts',
+  description: 'list all posts ordered by pub_date',
+  tags: %w[v1 posts],
+  required_request_params: %w[limit],
+  security: [{ "MyToken" => [] }],
+} do
+  # ...
+end
 ```
 
 **NOTE**: `description` key will override also the one provided by `RSpec::OpenAPI.description_builder` method.
 
 ### Enum Support
 
-You can specify enum values for string properties that should have a fixed set of allowed values. Since enums cannot be reliably inferred from test data, you can define them via the `enum` metadata option:
+You can specify enum values for string properties that should have a fixed set of allowed values. Since enums cannot be
+reliably inferred from test data, you can define them via the `enum` metadata option:
 
 ```rb
 it 'returns user status', openapi: {
@@ -431,7 +435,8 @@ end
 
 #### Request vs Response Enums
 
-By default, `enum` applies to both request and response bodies. If you need different enum values for request and response, use `request_enum` and `response_enum`:
+By default, `enum` applies to both request and response bodies. If you need different enum values for request and
+response, use `request_enum` and `response_enum`:
 
 ```rb
 it 'creates a task', openapi: {
@@ -447,6 +452,173 @@ it 'creates a task', openapi: {
 end
 ```
 
+### Dynamic-key Object Support (`additionalProperties`)
+
+When an endpoint returns (or accepts) an object whose keys are not part of its
+schema — for example a permissions map `{ "can_edit": true, "can_delete": false }`
+where new permissions can appear without an API change — rspec-openapi would
+otherwise capture the test response literally and emit each observed key as a
+fixed property. You can override this with the `additional_properties` metadata,
+which replaces the captured `properties` / `required` of the matched object with
+[`additionalProperties`](https://swagger.io/docs/specification/data-models/dictionaries/).
+
+Keys are dot-notation paths (the same scheme as `enum`); the empty string `''`
+targets the body root.
+
+```rb
+it 'returns a permission map', openapi: {
+  additional_properties: { 'data' => { type: 'boolean' } },
+} do
+  get '/api/v1/permissions'
+  # Response: { "data": { "can_edit": true, "can_delete": false } }
+  expect(response.status).to eq(200)
+end
+```
+
+This generates:
+
+```yaml
+schema:
+  type: object
+  properties:
+    data:
+      type: object
+      additionalProperties:
+        type: boolean
+  required:
+    - data
+```
+
+#### Root-level dynamic keys
+
+When the entire body is a dynamic dict, use `''` as the path:
+
+```rb
+it 'lists organisation memberships', openapi: {
+  additional_properties: { '' => { type: 'boolean' } },
+} do
+  get '/api/v1/organisations/acme/check_memberships'
+  # Response: { "user-hash-a": true, "user-hash-b": false }
+  expect(response.status).to eq(200)
+end
+```
+
+```yaml
+schema:
+  type: object
+  additionalProperties:
+    type: boolean
+```
+
+#### Schemas referenced via `$ref`
+
+The value of `additionalProperties` can be any schema, including a `$ref`:
+
+```rb
+it 'returns tags by id', openapi: {
+  additional_properties: { '' => { '$ref' => '#/components/schemas/Tag' } },
+} do
+  get '/tags'
+  expect(response.status).to eq(200)
+end
+```
+
+```yaml
+schema:
+  type: object
+  additionalProperties:
+    $ref: '#/components/schemas/Tag'
+```
+
+#### Request vs Response
+
+`additional_properties` applies to both request and response by default. Use
+`request_additional_properties` / `response_additional_properties` to scope to
+one side:
+
+```rb
+it 'records arbitrary metrics', openapi: {
+  request_additional_properties: { '' => { type: 'integer' } },
+} do
+  post '/metrics', params: { 'page_views' => 100, 'signups' => 5 }
+  expect(response.status).to eq(201)
+end
+```
+
+#### Forbidding extras with `false` (or `true`)
+
+Attaching `additionalProperties: false` forbid dynamic keys while `: true` (default)
+explicitly allow those.
+This is useful mostly for the `false` case, to prevent unexpected extras:
+
+```rb
+it 'returns a closed object', openapi: {
+  additional_properties: { '' => false },
+} do
+  get '/api/v1/profile'
+  # Response: { "id": 1, "name": "alice" }
+  expect(response.status).to eq(200)
+end
+```
+
+```yaml
+schema:
+  type: object
+  properties:
+    id: { type: integer }
+    name: { type: string }
+  required: [ id, name ]
+  additionalProperties: false
+```
+
+#### Hybrid objects (known keys + dynamic keys)
+
+When an object has both a fixed shape and dynamic keys, use `hybrid_additional_properties`
+(`request_hybrid_additional_properties` and `response_hybrid_additional_properties` to scope
+to one side). Captured properties stay; the supplied schema is attached as `additionalProperties`.
+
+At the root (whole body is the hybrid object):
+
+```rb
+it 'returns an item with custom attributes', openapi: {
+  hybrid_additional_properties: { '' => { type: 'string' } },
+} do
+  get '/api/v1/items/42'
+  # Response: { "id": 42, "attr_color": "red", "attr_size": "large" }
+  expect(response.status).to eq(200)
+end
+```
+
+```yaml
+schema:
+  type: object
+  properties:
+    id: { type: integer }
+    attr_color: { type: string }
+    attr_size: { type: string }
+  required: [ id, attr_color, attr_size ]
+  additionalProperties:
+    type: string
+```
+
+#### Notes on behavior
+
+- A hash schema in `additional_properties` fully replaces the captured
+  `properties` / `required` at the matched node. To keep observed properties
+  alongside `additionalProperties`, use `hybrid_additional_properties` or pass
+  a boolean.
+- Recursion stops once `additional_properties` matches a path with a hash
+  schema: nested overrides underneath (e.g. setting both `'data'` and
+  `'data.meta'`) won't be applied, because the supplied dictionary value
+  schema describes every child uniformly and isn't traversed further.
+  `hybrid_additional_properties` keeps observed properties so children are
+  still walked normally.
+- When migrating an existing schema (one previously generated with concrete
+  `properties` / `required`) by adding this metadata, the next regeneration
+  prunes the stale `properties` / `required` automatically. If you had
+  manually added `additionalProperties` to an object that also has
+  `properties`, that hybrid shape is preserved.
+
 ### Multiple Examples Mode
 
 You can generate multiple named examples for the same endpoint using `example_mode`:
@@ -480,23 +652,144 @@ responses:
             value: { ... }
 ```
 
+
 Available `example_mode` values:
+
 - `:single` (default) - generates single `example` field
 - `:multiple` - generates named `examples` with test descriptions as keys
 - `:none` - generates only schema, no examples
 
+`example_mode` also accepts a hash form so you can configure the request body and the response independently:
+
+```rb
+describe 'POST /sign_in', openapi: { example_mode: { request: :multiple, response: :multiple } } do
+  ...
+end
+```
+
+Missing keys default to `:single`, so `{ example_mode: { request: :multiple } }` keeps the response on `:single`.
+
+The bare symbol form maps as follows:
+
+| `example_mode` value                          | request side | response side |
+|-----------------------------------------------|--------------|---------------|
+| `:single` (default)                           | `:single`    | `:single`     |
+| `:none`                                       | `:none`      | `:none`       |
+| `:multiple`                                   | `:single` ⚠️ | `:multiple`   |
+| `{ request: :multiple, response: :multiple }` | `:multiple`  | `:multiple`   |
+
+⚠️ The bare `:multiple` shorthand is currently **response-only** to preserve the behavior that existed before
+request-side multi-examples were introduced. A future major release will change it to mean
+`{ request: :multiple, response: :multiple }`.
+
 The mode is inherited by nested contexts and can be overridden at any level.
 
 **Note:** If multiple examples resolve to the same example key for a single endpoint, the last one wins (overwrites).
 
+#### Request Body Multiple Examples
+
+With `example_mode: { request: :multiple }`, the generator produces named `examples:` for `requestBody`.
+This is useful when the same endpoint accepts mutually exclusive request shapes (e.g. OTP vs email/password sign-in),
+where merging them into a single `example:` would produce a nonsensical mixed payload.
+
+```rb
+describe 'POST /sign_in',
+         openapi: { example_mode: { request: :multiple, response: :multiple } } do
+  it 'with otp' do
+    post '/sign_in',
+         params: { auth_type: 'otp', otp: '123456' }.to_json,
+         headers: { 'CONTENT_TYPE' => 'application/json' }
+    expect(response.status).to eq(200)
+  end
+
+  it 'with email password' do
+    post '/sign_in',
+         params: { auth_type: 'email', email: 'a@b.c', password: 'pw' }.to_json,
+         headers: { 'CONTENT_TYPE' => 'application/json' }
+    expect(response.status).to eq(200)
+  end
+end
+```
+
+The generated `requestBody` keeps each shape as its own keyed example:
+
+```yaml
+requestBody:
+  content:
+    application/json:
+      schema:
+        type: object
+        properties:
+          auth_type: { type: string }
+          otp: { type: string }
+          email: { type: string }
+          password: { type: string }
+        required:
+          - auth_type
+      examples:
+        with_otp:
+          summary: with otp
+          value: { auth_type: otp, otp: '123456' }
+        with_email_password:
+          summary: with email password
+          value: { auth_type: email, email: a@b.c, password: pw }
+```
+
+The keys default to the test's description (normalized to lowercase + underscores).
+Override with `openapi: { example_key: 'custom_key', example_name: 'Custom Summary' }`,
+just like for response examples.
+
+##### Capturing 4xx requestBody examples
+
+When `request_example_mode` is `:single` (the default), tests with `status >= 400`
+are intentionally skipped for `requestBody` so that error payloads don't pollute
+the request schema. When `request: :multiple` is set, this short-circuit is lifted:
+each failing test contributes its own keyed example, so you can document
+validation-failure shapes alongside success shapes:
+
+```rb
+describe 'POST /sign_in',
+         openapi: { example_mode: { request: :multiple, response: :multiple } } do
+  it 'with otp' do
+    post '/sign_in', params: { auth_type: 'otp', otp: '123456' }.to_json,
+         headers: { 'CONTENT_TYPE' => 'application/json' }
+    expect(response.status).to eq(200)
+  end
+
+  it 'with missing fields' do
+    post '/sign_in', params: { auth_type: 'email' }.to_json,
+         headers: { 'CONTENT_TYPE' => 'application/json' }
+    expect(response.status).to eq(400)
+  end
+end
+```
+
+```yaml
+requestBody:
+  content:
+    application/json:
+      examples:
+        with_otp: { summary: with otp, value: { ... } }
+        with_missing_fields: { summary: with missing fields, value: { ... } }
+responses:
+  '200': { ... }
+  '400': { ... }
+```
+
+Mixing `:single` (some tests) with `:multiple` (others) on the same endpoint also works for `requestBody` - 
+the merger up-converts the singular `example:` into the `examples:` map automatically
+(see [Merge Behavior with Mixed Modes](#merge-behavior-with-mixed-modes) below).
+
 #### Merge Behavior with Mixed Modes
 
-When multiple tests target the same endpoint with different `example_mode` settings (even from different spec files), the merger automatically converts to `examples` format:
+When multiple tests target the same endpoint with different `example_mode` settings (even from different spec files),
+the merger automatically converts to `examples` format:
 
 ```rb
 # spec/requests/api_spec.rb
 describe 'GET /users' do
-  it 'returns users' do  # default :single mode
+  it 'returns users' do
+    # default :single mode
     get '/users'
     expect(response.status).to eq(200)
   end
@@ -512,6 +805,7 @@ end
 ```
 
 Result - both examples merged into `examples`:
+
 ```yaml
 responses:
   '200':
@@ -541,6 +835,7 @@ Even if you are not using `rspec` this gem might help you with its experimental
 Example:
 
 ```rb
+
 class TablesTest < ActionDispatch::IntegrationTest
   openapi!
 
@@ -558,9 +853,11 @@ class TablesTest < ActionDispatch::IntegrationTest
 end
 ```
 
-It should work with both classes inheriting from `ActionDispatch::IntegrationTest` and with classes using `Rack::Test` directly, as long as you call `openapi!` in your test class.
+It should work with both classes inheriting from `ActionDispatch::IntegrationTest` and with classes using `Rack::Test`
+directly, as long as you call `openapi!` in your test class.
 
-Please note that not all features present in the rspec integration work with minitest (yet). For example, custom per test case metadata is not supported. A custom `description_builder` will not work either.
+Please note that not all features present in the rspec integration work with minitest (yet). For example, custom per
+test case metadata is not supported. A custom `description_builder` will not work either.
 
 Run minitest with OPENAPI=1 to generate `doc/openapi.yaml` for your request specs.
 
@@ -579,15 +876,19 @@ Existing RSpec plugins which have OpenAPI integration:
 ## Acknowledgements
 
 * Heavily inspired by [r7kamura/autodoc](https://github.com/r7kamura/autodoc)
-* Orignally created by [k0kubun](https://github.com/k0kubun) and the ownership was transferred to [exoego](https://github.com/exoego) in 2022-11-29.
-
+* Orignally created by [k0kubun](https://github.com/k0kubun) and the ownership was transferred
+  to [exoego](https://github.com/exoego) in 2022-11-29.
 
 ## Releasing
 
-1. Ensure RubyGems trusted publishing is configured for this repo and gem ownership (see [Trusted publishing](https://guides.rubygems.org/trusted-publishing/)).
-2. In GitHub Actions, run the `prepare release` workflow manually. It bumps `lib/rspec/openapi/version.rb`, pushes `release/v<version>` to origin, and opens a PR.
+1. Ensure RubyGems trusted publishing is configured for this repo and gem ownership (
+   see [Trusted publishing](https://guides.rubygems.org/trusted-publishing/)).
+2. In GitHub Actions, run the `prepare release` workflow manually. It bumps `lib/rspec/openapi/version.rb`, pushes
+   `release/v<version>` to origin, and opens a PR.
 3. Review and merge the release PR into the default branch.
-4. Create and push a tag `v<version>` on the merged commit (via the GitHub UI or `git tag v<version>; git push origin v<version>`). Tag creation triggers the `Publish to RubyGems` workflow, which publishes the gem and creates the GitHub release notes automatically.
+4. Create and push a tag `v<version>` on the merged commit (via the GitHub UI or
+   `git tag v<version>; git push origin v<version>`). Tag creation triggers the `Publish to RubyGems` workflow, which
+   publishes the gem and creates the GitHub release notes automatically.
 
 ## License
 

data/lib/rspec/openapi/extractors/hanami.rb

@@ -54,8 +54,11 @@ class << RSpec::OpenAPI::Extractors::Hanami = Object.new
 
     return RSpec::OpenAPI::Extractors::Rack.request_attributes(request, example) unless route.routable?
 
-    summary, tags, formats, operation_id, required_request_params, security, description, deprecated, example_mode,
-      example_key, example_name, response_enum, request_enum = SharedExtractor.attributes(example)
+    summary, tags, formats, operation_id, required_request_params, security, description, deprecated,
+      request_example_mode, response_example_mode,
+      example_key, example_name, response_enum, request_enum, response_additional_properties,
+      request_additional_properties, response_hybrid_additional_properties,
+      request_hybrid_additional_properties = SharedExtractor.attributes(example)
 
     path = request.path
 
@@ -80,11 +83,16 @@ class << RSpec::OpenAPI::Extractors::Hanami = Object.new
       security,
       deprecated,
       formats,
-      example_mode,
+      request_example_mode,
+      response_example_mode,
       example_key,
       example_name,
       response_enum,
       request_enum,
+      response_additional_properties,
+      request_additional_properties,
+      response_hybrid_additional_properties,
+      request_hybrid_additional_properties,
     ]
   end
 

data/lib/rspec/openapi/extractors/rack.rb

@@ -6,8 +6,11 @@ class << RSpec::OpenAPI::Extractors::Rack = Object.new
   # @param [RSpec::Core::Example] example
   # @return Array
   def request_attributes(request, example)
-    summary, tags, formats, operation_id, required_request_params, security, description, deprecated, example_mode,
-      example_key, example_name, response_enum, request_enum = SharedExtractor.attributes(example)
+    summary, tags, formats, operation_id, required_request_params, security, description, deprecated,
+      request_example_mode, response_example_mode,
+      example_key, example_name, response_enum, request_enum, response_additional_properties,
+      request_additional_properties, response_hybrid_additional_properties,
+      request_hybrid_additional_properties = SharedExtractor.attributes(example)
 
     raw_path_params = request.path_parameters
     path = request.path
@@ -24,11 +27,16 @@ class << RSpec::OpenAPI::Extractors::Rack = Object.new
       security,
       deprecated,
       formats,
-      example_mode,
+      request_example_mode,
+      response_example_mode,
       example_key,
       example_name,
       response_enum,
       request_enum,
+      response_additional_properties,
+      request_additional_properties,
+      response_hybrid_additional_properties,
+      request_hybrid_additional_properties,
     ]
   end
 

data/lib/rspec/openapi/extractors/rails.rb

@@ -16,8 +16,11 @@ class << RSpec::OpenAPI::Extractors::Rails = Object.new
 
     raise "No route matched for #{fixed_request.request_method} #{fixed_request.path_info}" if route.nil?
 
-    summary, tags, formats, operation_id, required_request_params, security, description, deprecated, example_mode,
-      example_key, example_name, response_enum, request_enum = SharedExtractor.attributes(example)
+    summary, tags, formats, operation_id, required_request_params, security, description, deprecated,
+      request_example_mode, response_example_mode,
+      example_key, example_name, response_enum, request_enum, response_additional_properties,
+      request_additional_properties, response_hybrid_additional_properties,
+      request_hybrid_additional_properties = SharedExtractor.attributes(example)
 
     raw_path_params = request.path_parameters
 
@@ -40,16 +43,26 @@ class << RSpec::OpenAPI::Extractors::Rails = Object.new
       security,
       deprecated,
       formats,
-      example_mode,
+      request_example_mode,
+      response_example_mode,
       example_key,
       example_name,
       response_enum,
       request_enum,
+      response_additional_properties,
+      request_additional_properties,
+      response_hybrid_additional_properties,
+      request_hybrid_additional_properties,
     ]
   end
 
   # @param [RSpec::ExampleGroups::*] context
   def request_response(context)
+    # Read @integration_session directly so user-defined let(:request)/let(:response)
+    # don't shadow the real ActionDispatch objects we need for OpenAPI extraction.
+    session = context.instance_variable_get(:@integration_session)
+    return [session.request, session.response] if session
+
     [context.request, context.response]
   end
 

data/lib/rspec/openapi/extractors/shared_extractor.rb

@@ -4,6 +4,14 @@
 class SharedExtractor
   VALID_EXAMPLE_MODES = %i[none single multiple].freeze
 
+  EXAMPLE_MODE_MULTIPLE_SHORTHAND_WARNING = <<~MSG.tr("\n", ' ').strip.freeze
+    [rspec-openapi] DEPRECATION: example_mode: :multiple currently means
+    { request: :single, response: :multiple }. A future major version will
+    change it to { request: :multiple, response: :multiple } (both sides
+    multi). Specify the hash form explicitly to lock in current behavior or
+    opt in early.
+  MSG
+
   def self.attributes(example)
     metadata = merge_openapi_metadata(example.metadata)
     summary = metadata[:summary] || RSpec::OpenAPI.summary_builder.call(example)
@@ -14,7 +22,7 @@ class SharedExtractor
     security = metadata[:security]
     description = metadata[:description] || RSpec::OpenAPI.description_builder.call(example)
     deprecated = metadata[:deprecated]
-    example_mode = normalize_example_mode(metadata[:example_mode], example)
+    request_example_mode, response_example_mode = normalize_example_mode(metadata[:example_mode], example)
     example_name = metadata[:example_name] || RSpec::OpenAPI.example_name_builder.call(example)
     raw_example_key = metadata[:example_key] || example_name
     example_key = RSpec::OpenAPI::ExampleKey.normalize(raw_example_key)
@@ -25,8 +33,29 @@ class SharedExtractor
     response_enum = normalize_enum(metadata[:response_enum]) || base_enum
     request_enum = normalize_enum(metadata[:request_enum]) || base_enum
 
-    [summary, tags, formats, operation_id, required_request_params, security, description, deprecated, example_mode,
-     example_key, example_name, response_enum, request_enum,]
+    response_additional_properties, request_additional_properties = resolve_additional_properties(metadata)
+    response_hybrid_additional_properties, request_hybrid_additional_properties =
+      resolve_hybrid_additional_properties(metadata)
+
+    [summary, tags, formats, operation_id, required_request_params, security, description, deprecated,
+     request_example_mode, response_example_mode,
+     example_key, example_name, response_enum, request_enum, response_additional_properties,
+     request_additional_properties, response_hybrid_additional_properties,
+     request_hybrid_additional_properties,]
+  end
+
+  def self.resolve_additional_properties(metadata)
+    base = normalize_additional_properties(metadata[:additional_properties])
+    response = normalize_additional_properties(metadata[:response_additional_properties]) || base
+    request = normalize_additional_properties(metadata[:request_additional_properties]) || base
+    [response, request]
+  end
+
+  def self.resolve_hybrid_additional_properties(metadata)
+    base = normalize_additional_properties(metadata[:hybrid_additional_properties])
+    response = normalize_additional_properties(metadata[:response_hybrid_additional_properties]) || base
+    request = normalize_additional_properties(metadata[:request_hybrid_additional_properties]) || base
+    [response, request]
   end
 
   def self.normalize_enum(enum_hash)
@@ -36,6 +65,14 @@ class SharedExtractor
     enum_hash.transform_keys(&:to_s)
   end
 
+  def self.normalize_additional_properties(hash)
+    return nil if hash.nil? || hash.empty?
+
+    hash.each_with_object({}) do |(path, schema), result|
+      result[path.to_s] = RSpec::OpenAPI::KeyTransformer.symbolize(schema)
+    end
+  end
+
   def self.merge_openapi_metadata(metadata)
     collect_openapi_metadata(metadata).reduce({}, &:merge)
   end
@@ -54,9 +91,33 @@ class SharedExtractor
     end
   end
 
+  # Returns [request_mode, response_mode]. Accepts either a bare Symbol/String
+  # (applied to both sides, except :multiple which is treated as a backward-compat
+  # shorthand for { request: :single, response: :multiple } and emits a one-time
+  # deprecation warning) or a Hash with :request / :response keys.
   def self.normalize_example_mode(value, example = nil)
-    return :single if value.nil?
+    return %i[single single] if value.nil?
 
+    case value
+    when Hash
+      [
+        normalize_example_mode_hash_value(value, :request, example),
+        normalize_example_mode_hash_value(value, :response, example),
+      ]
+    when Symbol, String
+      mode = coerce_example_mode_value(value, example)
+      if mode == :multiple
+        warn_example_mode_multiple_shorthand
+        %i[single multiple]
+      else
+        [mode, mode]
+      end
+    else
+      raise ArgumentError, example_mode_error(value, example)
+    end
+  end
+
+  def self.coerce_example_mode_value(value, example)
     raise ArgumentError, example_mode_error(value, example) unless value.is_a?(String) || value.is_a?(Symbol)
 
     mode = value.to_s.strip.downcase.to_sym
@@ -65,9 +126,25 @@ class SharedExtractor
     raise ArgumentError, example_mode_error(value, example)
   end
 
+  def self.normalize_example_mode_hash_value(hash, key, example)
+    raw = hash[key]
+    raw = hash[key.to_s] if raw.nil?
+    return :single if raw.nil?
+
+    coerce_example_mode_value(raw, example)
+  end
+
+  def self.warn_example_mode_multiple_shorthand
+    return if @warned_example_mode_multiple_shorthand
+
+    @warned_example_mode_multiple_shorthand = true
+    Kernel.warn(EXAMPLE_MODE_MULTIPLE_SHORTHAND_WARNING)
+  end
+
   def self.example_mode_error(value, example)
     context = example&.full_description
     context = " (example: #{context})" if context
-    "example_mode must be one of #{VALID_EXAMPLE_MODES.inspect}, got #{value.inspect}#{context}"
+    "example_mode must be a Symbol/String in #{VALID_EXAMPLE_MODES.inspect} " \
+      "or a Hash with :request/:response keys, got #{value.inspect}#{context}"
   end
 end

data/lib/rspec/openapi/record.rb

@@ -20,7 +20,8 @@ RSpec::OpenAPI::Record = Struct.new(
   :security,              # @param [Array]  - [{securityScheme1: []}]
   :deprecated,            # @param [Boolean] - true
   :example_enabled,       # @param [Boolean] - true
-  :example_mode,          # @param [Symbol]  - :none | :single | :multiple
+  :request_example_mode,  # @param [Symbol]  - :none | :single | :multiple
+  :response_example_mode, # @param [Symbol]  - :none | :single | :multiple
   :status,                # @param [Integer] - 200
   :response_body,         # @param [Object]  - {"status" => "ok"}
   :response_headers,      # @param [Array]  - [["header_key1", "header_value1"], ["header_key2", "header_value2"]]
@@ -28,5 +29,9 @@ RSpec::OpenAPI::Record = Struct.new(
   :response_content_disposition, # @param [String]  - "inline"
   :response_enum,         # @param [Hash]    - {"status" => ["active", "inactive"], "user.role" => ["admin", "user"]}
   :request_enum,          # @param [Hash]    - {"type" => ["create", "update"]}
+  :response_additional_properties, # @param [Hash] - {"data" => { type: "boolean" }}
+  :request_additional_properties,  # @param [Hash] - {"meta" => { type: "string" }}
+  :response_hybrid_additional_properties, # @param [Hash] - {"data" => { type: "string" }}
+  :request_hybrid_additional_properties,  # @param [Hash] - {"meta" => { type: "string" }}
   keyword_init: true,
 )

data/lib/rspec/openapi/record_builder.rb

@@ -13,8 +13,10 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
 
     title = RSpec::OpenAPI.title.then { |t| t.is_a?(Proc) ? t.call(example) : t }
     path, summary, tags, operation_id, required_request_params, raw_path_params,
-      description, security, deprecated, formats, example_mode, example_key,
-      example_name, response_enum, request_enum = extractor.request_attributes(request, example)
+      description, security, deprecated, formats, request_example_mode, response_example_mode,
+      example_key, example_name, response_enum, request_enum, response_additional_properties,
+      request_additional_properties, response_hybrid_additional_properties,
+      request_hybrid_additional_properties = extractor.request_attributes(request, example)
 
     return if RSpec::OpenAPI.ignored_paths.any? { |ignored_path| path.match?(ignored_path) }
 
@@ -43,11 +45,16 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
       response_content_type: response.media_type,
       response_content_disposition: response.header['Content-Disposition'],
       example_enabled: RSpec::OpenAPI.enable_example,
-      example_mode: example_mode,
+      request_example_mode: request_example_mode,
+      response_example_mode: response_example_mode,
       example_key: example_key,
       example_name: example_name,
       response_enum: response_enum,
       request_enum: request_enum,
+      response_additional_properties: response_additional_properties,
+      request_additional_properties: request_additional_properties,
+      response_hybrid_additional_properties: response_hybrid_additional_properties,
+      request_hybrid_additional_properties: request_hybrid_additional_properties,
     ).freeze
   end
 

data/lib/rspec/openapi/schema_builder.rb

@@ -4,9 +4,15 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
   # @param [RSpec::OpenAPI::Record] record
   # @return [Hash]
   def build(record)
-    response = {
-      description: record.description,
-    }
+    response = if record.response_example_mode == :none
+                 # `:none` opts out of recording, so the description is provisional.
+                 # Stash it under a fallback key; SchemaCleaner promotes it to
+                 # `description` only if no documented test has set one. This makes
+                 # the merge result independent of RSpec's random execution order.
+                 { _fallback_description: record.description }
+               else
+                 { description: record.description }
+               end
 
     response_headers = build_response_headers(record)
     response[:headers] = response_headers unless response_headers.empty?
@@ -52,7 +58,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
     # If examples are globally disabled, always return schema-only content.
     return { content_type => { schema: schema }.compact } unless example_enabled?(record)
 
-    case record.example_mode
+    case record.response_example_mode
     when :none
       # Only schema, no examples
       {
@@ -74,8 +80,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
         content_type => {
           schema: schema,
           example: response_example(record, disposition: disposition),
-          _example_key: record.example_key,
-          _example_summary: example_summary(record),
+          **example_metadata(record),
         }.compact,
       }
     end
@@ -93,13 +98,21 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
   end
 
   def build_example_object(record, disposition:)
+    build_named_example(record, response_example(record, disposition: disposition))
+  end
+
+  def build_named_example(record, value)
     summary = example_summary(record)
     example = {}
     example[:summary] = summary if summary
-    example[:value] = response_example(record, disposition: disposition)
+    example[:value] = value
     example
   end
 
+  def example_metadata(record)
+    { _example_key: record.example_key, _example_summary: example_summary(record) }
+  end
+
   def example_summary(record)
     return nil unless example_summary_enabled?
     return nil if record.example_name.nil? || record.example_name.empty?
@@ -191,16 +204,33 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
 
   def build_request_body(record)
     return nil if record.request_content_type.nil?
-    return nil if record.status >= 400
+    return nil if record.status >= 400 && record.request_example_mode != :multiple
 
-    {
-      content: {
-        normalize_content_type(record.request_content_type) => {
-          schema: build_property(record.request_params, record: record, context: :request),
-          example: (build_example(record.request_params) if example_enabled?(record)),
-        }.compact,
-      },
-    }
+    content_type = normalize_content_type(record.request_content_type)
+    schema = build_property(record.request_params, record: record, context: :request)
+
+    return { content: { content_type => { schema: schema }.compact } } unless example_enabled?(record)
+
+    example = build_example(record.request_params)
+
+    body =
+      case record.request_example_mode
+      when :none
+        { schema: schema }
+      when :multiple
+        {
+          schema: schema,
+          examples: { record.example_key => build_named_example(record, example) },
+        }
+      else # :single (default)
+        {
+          schema: schema,
+          example: example,
+          **example_metadata(record),
+        }
+      end
+
+    { content: { content_type => body.compact } }
   end
 
   def build_property(value, disposition: nil, key: nil, record: nil, path: nil, context: nil)
@@ -217,13 +247,32 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
                            build_array_items_schema(value, record: record, path: path, context: context)
                          end
     when Hash
-      property[:properties] = {}.tap do |properties|
-        value.each do |k, v|
-          child_path = path ? "#{path}.#{k}" : k.to_s
-          properties[k] = build_property(v, record: record, key: k, path: child_path, context: context)
+      override = infer_additional_properties(path, record, context)
+      hybrid_override = infer_hybrid_additional_properties(path, record, context)
+      if override.is_a?(Hash) && !override.empty?
+        # Schema override: the object's keys are dynamic — replace captured
+        # `properties` / `required` with the supplied dictionary value schema.
+        property[:additionalProperties] = override
+      else
+        property[:properties] = {}.tap do |properties|
+          value.each do |k, v|
+            child_path = path ? "#{path}.#{k}" : k.to_s
+            properties[k] = build_property(v, record: record, key: k, path: child_path, context: context)
+          end
+        end
+        property = enrich_with_required_keys(property)
+        # Hybrid: keep the observed `properties` / `required` and attach
+        # `additionalProperties` alongside.
+        # - Boolean values are constraints (`false` forbids extras, `true`
+        #   explicitly allows them).
+        # - Hash schema values come from the dedicated `hybrid_additional_properties`
+        #   metadata, expressing "known keys + extras of this type".
+        if override == true || override == false
+          property[:additionalProperties] = override
+        elsif hybrid_override.is_a?(Hash) && !hybrid_override.empty?
+          property[:additionalProperties] = hybrid_override
         end
       end
-      property = enrich_with_required_keys(property)
     end
     property
   end
@@ -274,6 +323,36 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
     enum_hash[path.to_s]
   end
 
+  def infer_additional_properties(path, record, context)
+    return nil unless record
+
+    overrides = if context == :request
+                  record.request_additional_properties
+                else
+                  record.response_additional_properties
+                end
+    return nil unless overrides
+
+    # path is nil at the body root; nil.to_s == '' lets users target it via { '' => ... }.
+    # Use `key?` so a literal `false` override is distinguishable from "no override".
+    return nil unless overrides.key?(path.to_s)
+
+    overrides[path.to_s]
+  end
+
+  def infer_hybrid_additional_properties(path, record, context)
+    return nil unless record
+
+    overrides = if context == :request
+                  record.request_hybrid_additional_properties
+                else
+                  record.response_hybrid_additional_properties
+                end
+    return nil unless overrides
+
+    overrides[path.to_s]
+  end
+
   # Convert an always-String param to an appropriate type
   def try_cast(value)
     Integer(value)

data/lib/rspec/openapi/schema_cleaner.rb

@@ -86,6 +86,9 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
     hash.delete(:_example_key)
     hash.delete(:_example_summary)
     hash.delete(:_example_name)
+    if (fallback = hash.delete(:_fallback_description))
+      hash[:description] ||= fallback
+    end
 
     hash.each_value do |value|
       case value

data/lib/rspec/openapi/schema_merger.rb

@@ -25,6 +25,17 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
       return base
     end
 
+    # When the new spec converts an object to a dictionary (introduces
+    # `additionalProperties` on a node that previously had `properties` /
+    # `required`), drop the stale fields so the merged result reflects the
+    # new intent. We only prune when base does not already declare
+    # `additionalProperties`, to preserve manual edits that intentionally
+    # combine fixed and dynamic keys.
+    if spec.is_a?(Hash) && spec.key?(:additionalProperties) && !base.key?(:additionalProperties)
+      base.delete(:properties)
+      base.delete(:required)
+    end
+
     spec.each do |key, value|
       if base[key].is_a?(Hash) && value.is_a?(Hash)
         # Handle example/examples conflict - convert to examples when mixed

data/lib/rspec/openapi/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module OpenAPI
-    VERSION = '0.25.1'
+    VERSION = '0.26.0'
   end
 end

data/redocly.yaml

@@ -0,0 +1,31 @@
+# Config for `redocly lint` used by .github/workflows/validate-openapi.yml
+# to validate test-fixture OpenAPI documents shipped under spec/apps/.
+#
+# spec/apps/rails/doc/smart/openapi.yaml is intentionally excluded:
+# it is the input fixture for the smart-merge feature test (it contains
+# unresolved $refs by design), not a complete API description.
+extends:
+  - minimal
+apis:
+  rails-rspec-yaml:
+    root: spec/apps/rails/doc/rspec_openapi.yaml
+  rails-rspec-json:
+    root: spec/apps/rails/doc/rspec_openapi.json
+  rails-minitest-yaml:
+    root: spec/apps/rails/doc/minitest_openapi.yaml
+  rails-minitest-json:
+    root: spec/apps/rails/doc/minitest_openapi.json
+  rails-smart-expected:
+    root: spec/apps/rails/doc/smart/expected.yaml
+  roda-rspec-yaml:
+    root: spec/apps/roda/doc/rspec_openapi.yaml
+  roda-rspec-json:
+    root: spec/apps/roda/doc/rspec_openapi.json
+  roda-minitest-yaml:
+    root: spec/apps/roda/doc/minitest_openapi.yaml
+  roda-minitest-json:
+    root: spec/apps/roda/doc/minitest_openapi.json
+  hanami-yaml:
+    root: spec/apps/hanami/doc/openapi.yaml
+  hanami-json:
+    root: spec/apps/hanami/doc/openapi.json

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-openapi
 version: !ruby/object:Gem::Version
-  version: 0.25.1
+  version: 0.26.0
 platform: ruby
 authors:
 - Takashi Kokubun
@@ -67,6 +67,7 @@ files:
 - ".github/workflows/publish.yml"
 - ".github/workflows/rubocop.yml"
 - ".github/workflows/test.yml"
+- ".github/workflows/validate-openapi.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
@@ -102,6 +103,7 @@ files:
 - lib/rspec/openapi/schema_sorter.rb
 - lib/rspec/openapi/shared_hooks.rb
 - lib/rspec/openapi/version.rb
+- redocly.yaml
 - rspec-openapi.gemspec
 - scripts/rspec
 - scripts/rspec_with_simplecov
@@ -112,7 +114,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/exoego/rspec-openapi
   source_code_uri: https://github.com/exoego/rspec-openapi
-  changelog_uri: https://github.com/exoego/rspec-openapi/releases/tag/v0.25.1
+  changelog_uri: https://github.com/exoego/rspec-openapi/releases/tag/v0.26.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: