rspec-openapi 0.25.1 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fdb09465b214320cfd32bf020363827d17c3346d48cb7e724effc99df6bdf722
-  data.tar.gz: 9947b0df4b2af301473ff89cd52cd035d8a4cb129bd83f8aacef2fc4df107cd5
+  metadata.gz: 48caaf42c5ceaca30f18251c5bf29f427e71385d188f5abcc01295de3eab55b4
+  data.tar.gz: 171aacce0afccc800c6f5fb1e696dcd2f7d124ad0d09044e7797eb0a353452da
 SHA512:
-  metadata.gz: f17329553b8d2a02b196faba4ac592826557acb79648f364994614759e762608241d1310be6080873703af3b7f45d111db3509302f9ec22270c6c3c849bbd180
-  data.tar.gz: dd616bc6570e99d2b6439d4003bcadcdc9881613c6f4ba0428191ceef2c7c73dd185c5e385ea6c8af271f98d5c67d3e597062052d2c3bd7c59d1c0f6e75f0deb
+  metadata.gz: 9a6f77ff9446f74a56bc49576c6340176a58a6a0097e5d96a6b0a5f4334e06dfae55704a2e7dee3f1e12e160cea2a59933616ce2be8e60466f2c9ff10df460ac
+  data.tar.gz: f75d0f697a19d72408033e8e538643334649c2a7dab832c09e96d47f53f5be2660571d7a2b8b05cc5fdcb1d43fe86e9851f9d5d8e33a4fde8375d12120aa1c2f

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.27.1 or 0.28.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.yml

@@ -20,6 +20,10 @@ Style/ClassAndModuleChildren:
     - 'lib/rspec/openapi/version.rb'
 Layout/FirstArrayElementIndentation:
   EnforcedStyle: consistent
+Style/SymbolArray:
+  EnforcedStyle: brackets
+Style/WordArray:
+  EnforcedStyle: brackets
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'

data/.rubocop_todo.yml

@@ -1,45 +1,45 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2024-04-20 21:25:22 UTC using RuboCop version 1.62.1.
+# on 2026-05-25 01:13:29 UTC using RuboCop version 1.80.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 14
+# Offense count: 15
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
-  Max: 46
+  Max: 35
 
-# Offense count: 1
+# Offense count: 4
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 195
+  Max: 319
 
-# Offense count: 9
+# Offense count: 10
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/CyclomaticComplexity:
-  Max: 13
+  Max: 11
 
-# Offense count: 22
+# Offense count: 29
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 36
+  Max: 26
 
-# Offense count: 5
+# Offense count: 3
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Metrics/PerceivedComplexity:
-  Max: 13
+  Max: 11
 
 # Offense count: 1
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
 # SupportedStyles: snake_case, normalcase, non_integer
-# AllowedIdentifiers: capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
+# AllowedIdentifiers: TLS1_1, TLS1_2, capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
 Naming/VariableNumber:
   Exclude:
     - 'spec/integration_tests/roda_test.rb'
 
-# Offense count: 7
+# Offense count: 8
 # Configuration parameters: AllowedConstants.
 Style/Documentation:
   Exclude:

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