rspec-openapi 0.21.4 → 0.22.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10130361a7c2ee93e28be624decd6662215eaeb981a28981f02e5f1c95e82559
-  data.tar.gz: f32bbbe9f13c4a2b454ba4138b7c4825ca582f2ad32af73318c0a9c0c3d81147
+  metadata.gz: 4f37b771a178f8725b58190cecd8833eb49254bff604de7fef59bcb89b64cbf0
+  data.tar.gz: 956a8fd4c973a3c25112bdf13110cae26a6e35d146a037bd0a3af17f8b871596
 SHA512:
-  metadata.gz: ad8029bb23d7c9ec5b2a6c6898d82b906a061806e93912b166e6ab6b5464263dc936a3bbe86e821eea01a3d60e49f379327a966d8d1986e99258997f9132823e
-  data.tar.gz: 310ab5b4ff9b5a63555881679e77f0e1e829d3e1b296df79170db0915441bb70f5c8ebc553444574c93de80e6a7f510c2f26622c9df1052848dfc789df87d1f6
+  metadata.gz: a833eaee2f5d656eda27a40982aea8f8a8e737c82035cff713045a99fc19e2a29fcc810aa301da130d2739eb17fa1540d2df1b656489cbf21f1a889fe49397f5
+  data.tar.gz: a2a04437d06f870317d4c36bc4cbe9990beda5b5f2068eeca6f8b0e99b823a565862bb4572e924d4f49272c0a1e06ee7b4fb487d585a8b1bc5819755e57f9cd7

data/.github/workflows/create_release.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: 'Version to release (e.g. 0.21.3 or v0.21.3)'
+        description: 'Version to release (e.g. 0.22.2 or 0.23.0)'
         required: true
 
 jobs:
@@ -12,15 +12,11 @@ jobs:
     name: Prepare release PR
     runs-on: ubuntu-latest
 
-    permissions:
-      id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
-      contents: write # required to push release branch and open PR
-      pull-requests: write # required to create the release PR with GITHUB_TOKEN
-
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
+          token: ${{ secrets.PREPARE_RELEASE_PAT }}
 
       - name: Bump version.rb
         run: |
@@ -47,8 +43,27 @@ jobs:
               exit 1
             end
           RUBY
-
           ruby -pi -e "sub(/VERSION = .*/, \"VERSION = '$version'\")" lib/rspec/openapi/version.rb
+
+          VERSION_NO_V="$version" ruby - <<'RUBY'
+            version = ENV.fetch('VERSION_NO_V')
+            segments = version.split('.').map(&:to_i)
+            unless segments.size >= 3
+              warn "Version must have at least major.minor.patch: #{version}"
+              exit 1
+            end
+
+            major, minor, patch = segments
+            patch_bump = [major, minor, patch + 1].join('.')
+            minor_bump = [major, minor + 1, 0].join('.')
+            example = "Version to release (e.g. #{patch_bump} or #{minor_bump})"
+
+            path = ".github/workflows/create_release.yml"
+            content = File.read(path)
+            content.sub!(/description:\s*'Version to release \(e\.g\. [^']+\)'/,
+                         "description: '#{example}'")
+            File.write(path, content)
+          RUBY
           git status --short
 
       - name: Commit version bump
@@ -65,11 +80,12 @@ jobs:
           git push origin "HEAD:${release_branch}"
 
       - name: Open release PR
-        uses: peter-evans/create-pull-request@v6
+        uses: peter-evans/create-pull-request@v8
         with:
-          token: ${{ secrets.GITHUB_TOKEN }}
+          token: ${{ secrets.PREPARE_RELEASE_PAT }}
           add-paths: |
             lib/rspec/openapi/version.rb
+            .github/workflows/create_release.yml
           branch: ${{ env.RELEASE_BRANCH }}
           title: Release v${{ env.VERSION_NO_V }}
           commit-message: Bump version to ${{ env.VERSION_NO_V }}

data/.github/workflows/publish.yml

@@ -15,7 +15,7 @@ jobs:
       contents: write   # to create GitHub release
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -23,7 +23,7 @@ jobs:
         uses: ruby/setup-ruby@v1
         with:
           bundler-cache: true
-          ruby-version: ruby
+          ruby-version: '4.0'
 
       - name: Verify tag matches version.rb
         run: |

data/.github/workflows/rubocop.yml

@@ -19,7 +19,7 @@ jobs:
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: 3.3
+        ruby-version: '4.0'
         bundler-cache: true
 
     - name: Rubocop run

data/.github/workflows/test.yml

@@ -27,6 +27,8 @@ jobs:
             rails: 7.1.3.2
           - ruby: ruby:3.4
             rails: 8.0.2
+          - ruby: ruby:4.0
+            rails: 8.1.2
             coverage: coverage
     env:
       RAILS_VERSION: ${{ matrix.rails == '' && '6.1.6' || matrix.rails }}

data/Gemfile

@@ -8,11 +8,15 @@ gemspec
 gem 'rails', ENV['RAILS_VERSION'] || '6.0.6.1'
 
 if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.0.0')
-  gem 'hanami', ENV['HANAMI_VERSION'] || '2.1.0'
-  gem 'hanami-controller', ENV['HANAMI_VERSION'] || '2.1.0'
-  gem 'hanami-router', ENV['HANAMI_VERSION'] || '2.1.0'
-
-  gem 'dry-logger', '1.0.3'
+  if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('4.0.0')
+    gem 'dry-logger', '1.2.1'
+    gem 'hanami', ENV['HANAMI_VERSION'] || '2.3.2'
+  else
+    gem 'dry-logger', '1.0.3'
+    gem 'hanami', ENV['HANAMI_VERSION'] || '2.1.0'
+  end
+  gem 'hanami-controller'
+  gem 'hanami-router'
 end
 
 gem 'concurrent-ruby', '1.3.4'

data/README.md

@@ -135,9 +135,15 @@ RSpec::OpenAPI.title = -> (example) {
   end
 }
 
-# Disable generating `example`
+# Disable generating `example` globally
 RSpec::OpenAPI.enable_example = false
 
+# Customize example name generation (used for multiple examples)
+RSpec::OpenAPI.example_name_builder = -> (example) { example.description }
+
+# Disable generating example summaries for `examples`
+RSpec::OpenAPI.enable_example_summary = false
+
 # Change `info.version`
 RSpec::OpenAPI.application_version = '1.0.0'
 
@@ -360,6 +366,93 @@ Some examples' attributes can be overwritten via RSpec metadata options. Example
 
 **NOTE**: `description` key will override also the one provided by `RSpec::OpenAPI.description_builder` method.
 
+### Multiple Examples Mode
+
+You can generate multiple named examples for the same endpoint using `example_mode`:
+
+```rb
+describe '#index', openapi: { example_mode: :multiple } do
+  it 'with pagination' do
+    get '/tables', params: { page: 1, per: 10 }
+    expect(response.status).to eq(200)
+  end
+
+  it 'with filter' do
+    get '/tables', params: { filter: { name: 'test' } }
+    expect(response.status).to eq(200)
+  end
+end
+```
+
+This generates OpenAPI with multiple named examples:
+
+```yaml
+responses:
+  '200':
+    content:
+      application/json:
+        schema: { ... }
+        examples:
+          with_pagination:
+            value: { ... }
+          with_filter:
+            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
+
+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).
+
+#### 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:
+
+```rb
+# spec/requests/api_spec.rb
+describe 'GET /users' do
+  it 'returns users' do  # default :single mode
+    get '/users'
+    expect(response.status).to eq(200)
+  end
+end
+
+# spec/requests/admin_spec.rb
+describe 'GET /users', openapi: { example_mode: :multiple } do
+  it 'with admin privileges' do
+    get '/users', headers: { 'X-Admin': 'true' }
+    expect(response.status).to eq(200)
+  end
+end
+```
+
+Result - both examples merged into `examples`:
+```yaml
+responses:
+  '200':
+    content:
+      application/json:
+        examples:
+          returns_users:
+            value: { ... }
+          with_admin_privileges:
+            value: { ... }
+```
+
+To exclude specific tests from example generation, use `example_mode: :none`:
+
+```rb
+describe 'GET /users', openapi: { example_mode: :none } do
+  it 'edge case test' do
+    # This won't add examples to OpenAPI spec
+  end
+end
+```
+
 ## Experimental minitest support
 
 Even if you are not using `rspec` this gem might help you with its experimental support for `minitest`.

data/lib/rspec/openapi/example_key.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Normalizes example keys for OpenAPI examples field
+module RSpec::OpenAPI::ExampleKey
+  def self.normalize(value)
+    return nil if value.nil?
+
+    value.to_s.downcase.tr(' ', '_')
+  end
+end

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

@@ -56,15 +56,9 @@ class << RSpec::OpenAPI::Extractors::Hanami = Object.new
 
     return RSpec::OpenAPI::Extractors::Rack.request_attributes(request, example) unless route.routable?
 
-    metadata = merge_openapi_metadata(example.metadata)
-    summary = metadata[:summary] || RSpec::OpenAPI.summary_builder.call(example)
-    tags = metadata[:tags] || RSpec::OpenAPI.tags_builder.call(example)
-    formats = metadata[:formats] || RSpec::OpenAPI.formats_builder.curry.call(example)
-    operation_id = metadata[:operation_id]
-    required_request_params = metadata[:required_request_params] || []
-    security = metadata[:security]
-    description = metadata[:description] || RSpec::OpenAPI.description_builder.call(example)
-    deprecated = metadata[:deprecated]
+    summary, tags, formats, operation_id, required_request_params, security, description, deprecated, example_mode,
+      example_key, example_name = SharedExtractor.attributes(example)
+
     path = request.path
 
     raw_path_params = route.params
@@ -88,6 +82,9 @@ class << RSpec::OpenAPI::Extractors::Hanami = Object.new
       security,
       deprecated,
       formats,
+      example_mode,
+      example_key,
+      example_name,
     ]
   end
 
@@ -102,24 +99,6 @@ class << RSpec::OpenAPI::Extractors::Hanami = Object.new
 
   private
 
-  def merge_openapi_metadata(metadata)
-    collect_openapi_metadata(metadata).reduce({}, &:merge)
-  end
-
-  def collect_openapi_metadata(metadata)
-    [].tap do |result|
-      current = metadata
-
-      while current
-        [current[:example_group], current].each do |meta|
-          result.unshift(meta[:openapi]) if meta&.dig(:openapi)
-        end
-
-        current = current[:parent_example_group]
-      end
-    end
-  end
-
   def add_id(path, route)
     return path if route.params.empty?
 

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

@@ -6,18 +6,13 @@ class << RSpec::OpenAPI::Extractors::Rack = Object.new
   # @param [RSpec::Core::Example] example
   # @return Array
   def request_attributes(request, example)
-    metadata = merge_openapi_metadata(example.metadata)
-    summary = metadata[:summary] || RSpec::OpenAPI.summary_builder.call(example)
-    tags = metadata[:tags] || RSpec::OpenAPI.tags_builder.call(example)
-    formats = metadata[:formats] || RSpec::OpenAPI.formats_builder.curry.call(example)
-    operation_id = metadata[:operation_id]
-    required_request_params = metadata[:required_request_params] || []
-    security = metadata[:security]
-    description = metadata[:description] || RSpec::OpenAPI.description_builder.call(example)
-    deprecated = metadata[:deprecated]
+    summary, tags, formats, operation_id, required_request_params, security, description, deprecated, example_mode,
+      example_key, example_name = SharedExtractor.attributes(example)
+
     raw_path_params = request.path_parameters
     path = request.path
     summary ||= "#{request.method} #{path}"
+
     [
       path,
       summary,
@@ -29,6 +24,9 @@ class << RSpec::OpenAPI::Extractors::Rack = Object.new
       security,
       deprecated,
       formats,
+      example_mode,
+      example_key,
+      example_name,
     ]
   end
 
@@ -40,24 +38,4 @@ class << RSpec::OpenAPI::Extractors::Rack = Object.new
 
     [request, response]
   end
-
-  private
-
-  def merge_openapi_metadata(metadata)
-    collect_openapi_metadata(metadata).reduce({}, &:merge)
-  end
-
-  def collect_openapi_metadata(metadata)
-    [].tap do |result|
-      current = metadata
-
-      while current
-        [current[:example_group], current].each do |meta|
-          result.unshift(meta[:openapi]) if meta&.dig(:openapi)
-        end
-
-        current = current[:parent_example_group]
-      end
-    end
-  end
 end

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

@@ -16,16 +16,9 @@ class << RSpec::OpenAPI::Extractors::Rails = Object.new
 
     raise "No route matched for #{fixed_request.request_method} #{fixed_request.path_info}" if route.nil?
 
-    metadata = merge_openapi_metadata(example.metadata)
-    summary = metadata[:summary] || RSpec::OpenAPI.summary_builder.call(example)
-    tags = metadata[:tags] || RSpec::OpenAPI.tags_builder.call(example)
-    formats = metadata[:formats] || RSpec::OpenAPI.formats_builder.curry.call(example)
-
-    operation_id = metadata[:operation_id]
-    required_request_params = metadata[:required_request_params] || []
-    security = metadata[:security]
-    description = metadata[:description] || RSpec::OpenAPI.description_builder.call(example)
-    deprecated = metadata[:deprecated]
+    summary, tags, formats, operation_id, required_request_params, security, description, deprecated, example_mode,
+      example_key, example_name = SharedExtractor.attributes(example)
+
     raw_path_params = request.path_parameters
 
     summary ||= route.requirements[:action]
@@ -47,6 +40,9 @@ class << RSpec::OpenAPI::Extractors::Rails = Object.new
       security,
       deprecated,
       formats,
+      example_mode,
+      example_key,
+      example_name,
     ]
   end
 
@@ -57,24 +53,6 @@ class << RSpec::OpenAPI::Extractors::Rails = Object.new
 
   private
 
-  def merge_openapi_metadata(metadata)
-    collect_openapi_metadata(metadata).reduce({}, &:merge)
-  end
-
-  def collect_openapi_metadata(metadata)
-    [].tap do |result|
-      current = metadata
-
-      while current
-        [current[:example_group], current].each do |meta|
-          result.unshift(meta[:openapi]) if meta&.dig(:openapi)
-        end
-
-        current = current[:parent_example_group]
-      end
-    end
-  end
-
   # @param [ActionDispatch::Request] request
   def find_rails_route(request, app: Rails.application, path_prefix: '')
     app.routes.router.recognize(request) do |route, _parameters|

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Shared extractor for extracting OpenAPI metadata from RSpec examples
+class SharedExtractor
+  VALID_EXAMPLE_MODES = %i[none single multiple].freeze
+
+  def self.attributes(example)
+    metadata = merge_openapi_metadata(example.metadata)
+    summary = metadata[:summary] || RSpec::OpenAPI.summary_builder.call(example)
+    tags = metadata[:tags] || RSpec::OpenAPI.tags_builder.call(example)
+    formats = metadata[:formats] || RSpec::OpenAPI.formats_builder.curry.call(example)
+    operation_id = metadata[:operation_id]
+    required_request_params = metadata[:required_request_params] || []
+    security = metadata[:security]
+    description = metadata[:description] || RSpec::OpenAPI.description_builder.call(example)
+    deprecated = metadata[:deprecated]
+    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)
+    example_key = 'default' if example_key.nil? || example_key.empty?
+
+    [summary, tags, formats, operation_id, required_request_params, security, description, deprecated, example_mode,
+     example_key, example_name,]
+  end
+
+  def self.merge_openapi_metadata(metadata)
+    collect_openapi_metadata(metadata).reduce({}, &:merge)
+  end
+
+  def self.collect_openapi_metadata(metadata)
+    [].tap do |result|
+      current = metadata
+
+      while current
+        [current[:example_group], current].each do |meta|
+          result.unshift(meta[:openapi]) if meta&.dig(:openapi)
+        end
+
+        current = current[:parent_example_group]
+      end
+    end
+  end
+
+  def self.normalize_example_mode(value, example = nil)
+    return :single if value.nil?
+
+    raise ArgumentError, example_mode_error(value, example) unless value.is_a?(String) || value.is_a?(Symbol)
+
+    mode = value.to_s.strip.downcase.to_sym
+    return mode if VALID_EXAMPLE_MODES.include?(mode)
+
+    raise ArgumentError, example_mode_error(value, example)
+  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}"
+  end
+end

data/lib/rspec/openapi/key_transformer.rb

@@ -4,7 +4,28 @@ class << RSpec::OpenAPI::KeyTransformer = Object.new
   def symbolize(value)
     case value
     when Hash
-      value.to_h { |k, v| [k.to_sym, symbolize(v)] }
+      value.to_h do |k, v|
+        if k.to_sym == :examples
+          [k.to_sym, symbolize_examples(v)]
+        else
+          [k.to_sym, symbolize(v)]
+        end
+      end
+    when Array
+      value.map { |v| symbolize(v) }
+    else
+      value
+    end
+  end
+
+  def symbolize_examples(value)
+    case value
+    when Hash
+      value.to_h do |k, v|
+        k = k.downcase.tr(' ', '_') unless k.is_a?(Symbol)
+
+        [k.to_sym, symbolize(v)]
+      end
     when Array
       value.map { |v| symbolize(v) }
     else

data/lib/rspec/openapi/record.rb

@@ -15,8 +15,12 @@ RSpec::OpenAPI::Record = Struct.new(
   :formats,               # @param [Proc]    - ->(key) { key.end_with?('_at') ? 'date-time' : nil }
   :operation_id,          # @param [String]   - "request-1234"
   :description,           # @param [String]  - "returns a status"
+  :example_key,           # @param [String]  - "with_flat_query_parameters"
+  :example_name,          # @param [String]  - "with flat query parameters"
   :security,              # @param [Array]  - [{securityScheme1: []}]
   :deprecated,            # @param [Boolean] - true
+  :example_enabled,       # @param [Boolean] - true
+  :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"]]

data/lib/rspec/openapi/record_builder.rb

@@ -12,8 +12,8 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
     return if request.nil?
 
     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 =
-      extractor.request_attributes(request, example)
+    path, summary, tags, operation_id, required_request_params, raw_path_params, description, security, deprecated,
+      formats, example_mode, example_key, example_name = extractor.request_attributes(request, example)
 
     return if RSpec::OpenAPI.ignored_paths.any? { |ignored_path| path.match?(ignored_path) }
 
@@ -41,6 +41,10 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
       response_headers: response_headers,
       response_content_type: response.media_type,
       response_content_disposition: response.header['Content-Disposition'],
+      example_enabled: RSpec::OpenAPI.enable_example,
+      example_mode: example_mode,
+      example_key: example_key,
+      example_name: example_name,
     ).freeze
   end
 

data/lib/rspec/openapi/schema_builder.rb

@@ -15,14 +15,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
       disposition = normalize_content_disposition(record.response_content_disposition)
 
       has_content = !normalize_content_type(record.response_content_type).nil?
-      if has_content
-        response[:content] = {
-          normalize_content_type(record.response_content_type) => {
-            schema: build_property(record.response_body, disposition: disposition, record: record),
-            example: response_example(record, disposition: disposition),
-          }.compact,
-        }
-      end
+      response[:content] = build_content(disposition, record) if has_content
     end
 
     http_method = record.http_method.downcase
@@ -52,19 +45,74 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
     %w[delete get].include?(http_method)
   end
 
+  def build_content(disposition, record)
+    content_type = normalize_content_type(record.response_content_type)
+    schema = build_property(record.response_body, disposition: disposition, record: record)
+
+    # If examples are globally disabled, always return schema-only content.
+    return { content_type => { schema: schema }.compact } unless example_enabled?(record)
+
+    case record.example_mode
+    when :none
+      # Only schema, no examples
+      {
+        content_type => {
+          schema: schema,
+        }.compact,
+      }
+    when :multiple
+      # Multiple named examples
+      {
+        content_type => {
+          schema: schema,
+          examples: { record.example_key => build_example_object(record, disposition: disposition) },
+        }.compact,
+      }
+    else # :single (default)
+      # Single example + store name for possible merger conversion
+      {
+        content_type => {
+          schema: schema,
+          example: response_example(record, disposition: disposition),
+          _example_key: record.example_key,
+          _example_summary: example_summary(record),
+        }.compact,
+      }
+    end
+  end
+
   def enrich_with_required_keys(obj)
     obj[:required] = obj[:properties]&.keys || []
     obj
   end
 
   def response_example(record, disposition:)
-    return nil if !example_enabled? || disposition
+    return nil if !example_enabled?(record) || disposition
 
     record.response_body
   end
 
-  def example_enabled?
-    RSpec::OpenAPI.enable_example
+  def build_example_object(record, disposition:)
+    summary = example_summary(record)
+    example = {}
+    example[:summary] = summary if summary
+    example[:value] = response_example(record, disposition: disposition)
+    example
+  end
+
+  def example_summary(record)
+    return nil unless example_summary_enabled?
+    return nil if record.example_name.nil? || record.example_name.empty?
+
+    record.example_name
+  end
+
+  def example_enabled?(record)
+    record.example_enabled
+  end
+
+  def example_summary_enabled?
+    RSpec::OpenAPI.enable_example_summary
   end
 
   def build_parameters(record)
@@ -74,7 +122,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
         in: 'path',
         required: true,
         schema: build_property(try_cast(value), key: key, record: record),
-        example: (try_cast(value) if example_enabled?),
+        example: (try_cast(value) if example_enabled?(record)),
       }.compact
     end
 
@@ -84,7 +132,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
         in: 'query',
         required: record.required_request_params.include?(key),
         schema: build_property(try_cast(value), key: key, record: record),
-        example: (try_cast(value) if example_enabled?),
+        example: (try_cast(value) if example_enabled?(record)),
       }.compact
     end
 
@@ -94,7 +142,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
         in: 'header',
         required: true,
         schema: build_property(try_cast(value), key: key, record: record),
-        example: (try_cast(value) if example_enabled?),
+        example: (try_cast(value) if example_enabled?(record)),
       }.compact
     end
 
@@ -135,7 +183,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
       content: {
         normalize_content_type(record.request_content_type) => {
           schema: build_property(record.request_params, record: record),
-          example: (build_example(record.request_params) if example_enabled?),
+          example: (build_example(record.request_params) if example_enabled?(record)),
         }.compact,
       },
     }
@@ -273,7 +321,6 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
         unique_types = property_variations.map { |p| p[:type] }.compact.uniq
 
         if unique_types.size > 1
-          # Different types detected - create oneOf
           unique_props = property_variations.map { |p| p.reject { |k, _| k == :nullable } }.uniq
           merged_schema[:properties][key] = { oneOf: unique_props }
         else
@@ -315,7 +362,9 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
         nullable_only = all_prop_variations.select { |p| p && p.keys == [:nullable] }
         prop_variations = all_prop_variations.select { |p| p && p.keys != [:nullable] }.compact
 
-        has_nullable = all_prop_variations.any?(&:nil?) || nullable_only.any?
+        has_nullable = all_prop_variations.any? do |v|
+          v.nil? || (v.is_a?(Hash) && v[:nullable] == true)
+        end || nullable_only.any?
 
         if prop_variations.empty? && has_nullable
           merged[:properties][key] = { nullable: true }
@@ -324,8 +373,21 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
           merged[:properties][key][:nullable] = true if has_nullable
         elsif prop_variations.size > 1
           prop_types = prop_variations.map { |p| p[:type] }.compact.uniq
-
-          if prop_types.size == 1
+          has_one_of = prop_variations.any? { |p| p.key?(:oneOf) }
+
+          if has_one_of
+            all_options = []
+            prop_variations.each do |prop|
+              clean_prop = prop.reject { |k, _| k == :nullable }
+              if clean_prop.key?(:oneOf)
+                all_options.concat(clean_prop[:oneOf])
+              else
+                all_options << clean_prop unless clean_prop.empty?
+              end
+            end
+            all_options.uniq!
+            merged[:properties][key] = { oneOf: all_options }
+          elsif prop_types.size == 1
             # Only recursively merge if it's an object type
             merged[:properties][key] = if prop_types.first == 'object'
                                          build_merged_schema_from_variations(prop_variations)

data/lib/rspec/openapi/schema_cleaner.rb

@@ -32,10 +32,16 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
     # cleanup requestBody
     cleanup_hash!(base, spec, 'paths.*.*.requestBody.content.application/json.schema.properties.*')
     cleanup_hash!(base, spec, 'paths.*.*.requestBody.content.application/json.example.*')
+    cleanup_hash!(base, spec, 'paths.*.*.requestBody.content.application/json.examples.*')
 
     # cleanup responses
     cleanup_hash!(base, spec, 'paths.*.*.responses.*.content.application/json.schema.properties.*')
     cleanup_hash!(base, spec, 'paths.*.*.responses.*.content.application/json.example.*')
+    cleanup_hash!(base, spec, 'paths.*.*.responses.*.content.application/json.examples.*')
+
+    # cleanup temporary fields used for internal processing
+    cleanup_temporary_fields!(base)
+
     base
   end
 
@@ -71,6 +77,24 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
 
   private
 
+  # Recursively remove temporary fields like :_example_key and :_example_name from the schema
+  def cleanup_temporary_fields!(hash)
+    return unless hash.is_a?(Hash)
+
+    hash.delete(:_example_key)
+    hash.delete(:_example_summary)
+    hash.delete(:_example_name)
+
+    hash.each_value do |value|
+      case value
+      when Hash
+        cleanup_temporary_fields!(value)
+      when Array
+        value.each { |item| cleanup_temporary_fields!(item) if item.is_a?(Hash) }
+      end
+    end
+  end
+
   def remove_parameters_conflicting_with_security_scheme!(path_definition, security_scheme, security_scheme_name)
     return unless path_definition[:security]
     return unless path_definition[:parameters]

data/lib/rspec/openapi/schema_merger.rb

@@ -25,6 +25,9 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
 
     spec.each do |key, value|
       if base[key].is_a?(Hash) && value.is_a?(Hash)
+        # Handle example/examples conflict - convert to examples when mixed
+        normalize_example_fields!(base[key], value)
+
         # If the new value has oneOf, replace the entire value instead of merging
         if value.key?(:oneOf)
           base[key] = value
@@ -77,6 +80,26 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
 
   SIMILARITY_THRESHOLD = 0.5
 
+  # Normalize example/examples fields when there's a conflict
+  # OpenAPI spec doesn't allow both example and examples in the same object
+  def normalize_example_fields!(base, spec)
+    if base.key?(:example) && spec.key?(:examples)
+      convert_example_to_examples!(base)
+    elsif base.key?(:examples) && spec.key?(:example)
+      convert_example_to_examples!(spec)
+    end
+  end
+
+  def convert_example_to_examples!(hash)
+    name = RSpec::OpenAPI::ExampleKey.normalize(hash.delete(:_example_key)) || 'default'
+    summary = hash.delete(:_example_summary)
+    value = hash.delete(:example)
+    example = {}
+    example[:summary] = summary if summary
+    example[:value] = value
+    hash[:examples] = { name => example }
+  end
+
   def merge_closest_match!(options, spec)
     score, option = options.map { |option| [similarity(option, spec), option] }.max_by(&:first)
 

data/lib/rspec/openapi/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module OpenAPI
-    VERSION = '0.21.4'
+    VERSION = '0.22.1'
   end
 end

data/lib/rspec/openapi.rb

@@ -7,12 +7,14 @@ require 'rspec/openapi/record_builder'
 require 'rspec/openapi/result_recorder'
 require 'rspec/openapi/schema_builder'
 require 'rspec/openapi/schema_file'
+require 'rspec/openapi/example_key'
 require 'rspec/openapi/schema_merger'
 require 'rspec/openapi/schema_cleaner'
 require 'rspec/openapi/schema_sorter'
 require 'rspec/openapi/key_transformer'
 require 'rspec/openapi/shared_hooks'
 require 'rspec/openapi/extractors'
+require 'rspec/openapi/extractors/shared_extractor'
 require 'rspec/openapi/extractors/rack'
 
 module RSpec::OpenAPI
@@ -30,7 +32,9 @@ module RSpec::OpenAPI
   @title = File.basename(Dir.pwd)
   @comment = nil
   @enable_example = true
+  @enable_example_summary = true
   @description_builder = ->(example) { example.description }
+  @example_name_builder = :description.to_proc
   @summary_builder = ->(example) { example.metadata[:summary] }
   @tags_builder = ->(example) { example.metadata[:tags] }
   @formats_builder = ->(example) { example.metadata[:formats] }
@@ -54,7 +58,9 @@ module RSpec::OpenAPI
                   :title,
                   :comment,
                   :enable_example,
+                  :enable_example_summary,
                   :description_builder,
+                  :example_name_builder,
                   :summary_builder,
                   :tags_builder,
                   :formats_builder,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-openapi
 version: !ruby/object:Gem::Version
-  version: 0.21.4
+  version: 0.22.1
 platform: ruby
 authors:
 - Takashi Kokubun
@@ -82,10 +82,12 @@ files:
 - lib/rspec/openapi.rb
 - lib/rspec/openapi/components_updater.rb
 - lib/rspec/openapi/default_schema.rb
+- lib/rspec/openapi/example_key.rb
 - lib/rspec/openapi/extractors.rb
 - lib/rspec/openapi/extractors/hanami.rb
 - lib/rspec/openapi/extractors/rack.rb
 - lib/rspec/openapi/extractors/rails.rb
+- lib/rspec/openapi/extractors/shared_extractor.rb
 - lib/rspec/openapi/hash_helper.rb
 - lib/rspec/openapi/key_transformer.rb
 - lib/rspec/openapi/minitest_hooks.rb
@@ -110,7 +112,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.21.4
+  changelog_uri: https://github.com/exoego/rspec-openapi/releases/tag/v0.22.1
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -126,7 +128,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Generate OpenAPI schema from RSpec request specs
 test_files: []