rspec-openapi 0.23.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9de2ab7b530ea8a400d157e5296b042e7a1988b84537a2def73007a169d530fe
-  data.tar.gz: 4550f2cee402ccbd45c2722a8bac19550494e2822ea5344a09294ba06845901b
+  metadata.gz: 65e97b91c81a4798c7907d907174d8c7efe874ad26dd3d630db2c86db97f913d
+  data.tar.gz: a593eaf58214a7bc5578f3cee065d263d7b494507727ac05c60111d01b0a2a7d
 SHA512:
-  metadata.gz: 9ad939c9bfc561a429838f5e6149c1cefbe7c6e1346c8d0cf95fd83fa7cbd55654c7dcb9d889d9fdb8f6eead6c35c6eb316d35445679ba6cabc3b8e7cc2a5022
-  data.tar.gz: bac87ded3a5f9cbcbedf675b8a29e18ea53ec87f3abc396d56872279a6c88c879afcb09589db87796736b947cef34ef9b59af49e903e297c6aa0c4389f5b2465
+  metadata.gz: 3e88fae82f5452b748d2ade83adc141fff0e888946c48ec3219999012bd75a7162e678d89af1e1ccb584e14250739715e0ffd53ec1b1ff101080ca2abd44ba82
+  data.tar.gz: e49fdd879b02d43fe0f8ac4ef2d443b7a0366c5f133d5012f771be380c706b9fa28597f6bd6e6e111bee599bee26e5ae71f8dec262e4bf6070c679790e42d654

data/.github/workflows/create_release.yml

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

data/Gemfile

@@ -24,7 +24,7 @@ gem 'concurrent-ruby', '1.3.4'
 gem 'roda'
 
 gem 'rails-dom-testing', '~> 2.2'
-gem 'rspec-rails'
+gem 'rspec-rails', '>= 5.0'
 
 group :test do
   gem 'simplecov', git: 'https://github.com/exoego/simplecov.git', branch: 'branch-fix'

data/README.md

@@ -366,6 +366,87 @@ 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.
 
+### 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:
+
+```rb
+it 'returns user status', openapi: {
+  enum: {
+    'status' => %w[active inactive suspended],
+  },
+} do
+  get '/users/1'
+  expect(response.status).to eq(200)
+end
+```
+
+This generates:
+
+```yaml
+schema:
+  type: object
+  properties:
+    status:
+      type: string
+      enum:
+        - active
+        - inactive
+        - suspended
+```
+
+#### Nested Paths
+
+For nested objects, use dot notation to specify the path:
+
+```rb
+it 'returns user with role', openapi: {
+  enum: {
+    'status' => %w[active inactive],
+    'user.role' => %w[admin user guest],
+  },
+} do
+  get '/teams/1'
+  # Response: { "status": "active", "user": { "name": "John", "role": "admin" } }
+  expect(response.status).to eq(200)
+end
+```
+
+#### Array Items
+
+For properties inside array items, use the array property name followed by the item property:
+
+```rb
+it 'returns items with status', openapi: {
+  enum: {
+    'items.status' => %w[pending completed failed],
+    'items.priority' => %w[high medium low],
+  },
+} do
+  get '/tasks'
+  # Response: { "items": [{ "id": 1, "status": "pending", "priority": "high" }] }
+  expect(response.status).to eq(200)
+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`:
+
+```rb
+it 'creates a task', openapi: {
+  request_enum: {
+    'action' => %w[create update delete],
+  },
+  response_enum: {
+    'status' => %w[pending processing completed],
+  },
+} do
+  post '/tasks', params: { action: 'create', name: 'New Task' }
+  expect(response.status).to eq(201)
+end
+```
+
 ### Multiple Examples Mode
 
 You can generate multiple named examples for the same endpoint using `example_mode`:

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

@@ -57,7 +57,7 @@ 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 = SharedExtractor.attributes(example)
+      example_key, example_name, response_enum, request_enum = SharedExtractor.attributes(example)
 
     path = request.path
 
@@ -85,6 +85,8 @@ class << RSpec::OpenAPI::Extractors::Hanami = Object.new
       example_mode,
       example_key,
       example_name,
+      response_enum,
+      request_enum,
     ]
   end
 

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

@@ -7,7 +7,7 @@ class << RSpec::OpenAPI::Extractors::Rack = Object.new
   # @return Array
   def request_attributes(request, example)
     summary, tags, formats, operation_id, required_request_params, security, description, deprecated, example_mode,
-      example_key, example_name = SharedExtractor.attributes(example)
+      example_key, example_name, response_enum, request_enum = SharedExtractor.attributes(example)
 
     raw_path_params = request.path_parameters
     path = request.path
@@ -27,6 +27,8 @@ class << RSpec::OpenAPI::Extractors::Rack = Object.new
       example_mode,
       example_key,
       example_name,
+      response_enum,
+      request_enum,
     ]
   end
 

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

@@ -17,7 +17,7 @@ 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 = SharedExtractor.attributes(example)
+      example_key, example_name, response_enum, request_enum = SharedExtractor.attributes(example)
 
     raw_path_params = request.path_parameters
 
@@ -43,6 +43,8 @@ class << RSpec::OpenAPI::Extractors::Rails = Object.new
       example_mode,
       example_key,
       example_name,
+      response_enum,
+      request_enum,
     ]
   end
 

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

@@ -20,8 +20,20 @@ class SharedExtractor
     example_key = RSpec::OpenAPI::ExampleKey.normalize(raw_example_key)
     example_key = 'default' if example_key.nil? || example_key.empty?
 
+    # Enum support: response_enum and request_enum can override the general enum
+    base_enum = normalize_enum(metadata[:enum])
+    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,]
+     example_key, example_name, response_enum, request_enum,]
+  end
+
+  def self.normalize_enum(enum_hash)
+    return nil if enum_hash.nil? || enum_hash.empty?
+
+    # Convert all keys to strings for consistent lookup
+    enum_hash.transform_keys(&:to_s)
   end
 
   def self.merge_openapi_metadata(metadata)

data/lib/rspec/openapi/record.rb

@@ -26,5 +26,7 @@ RSpec::OpenAPI::Record = Struct.new(
   :response_headers,      # @param [Array]  - [["header_key1", "header_value1"], ["header_key2", "header_value2"]]
   :response_content_type, # @param [String]  - "application/json"
   :response_content_disposition, # @param [String]  - "inline"
+  :response_enum,         # @param [Hash]    - {"status" => ["active", "inactive"], "user.role" => ["admin", "user"]}
+  :request_enum,          # @param [Hash]    - {"type" => ["create", "update"]}
   keyword_init: true,
 )

data/lib/rspec/openapi/record_builder.rb

@@ -13,7 +13,7 @@ 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 = extractor.request_attributes(request, example)
+      formats, example_mode, example_key, example_name, response_enum, request_enum = extractor.request_attributes(request, example)
 
     return if RSpec::OpenAPI.ignored_paths.any? { |ignored_path| path.match?(ignored_path) }
 
@@ -45,6 +45,8 @@ class << RSpec::OpenAPI::RecordBuilder = Object.new
       example_mode: example_mode,
       example_key: example_key,
       example_name: example_name,
+      response_enum: response_enum,
+      request_enum: request_enum,
     ).freeze
   end
 

data/lib/rspec/openapi/schema_builder.rb

@@ -47,7 +47,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
 
   def build_content(disposition, record)
     content_type = normalize_content_type(record.response_content_type)
-    schema = build_property(record.response_body, disposition: disposition, record: record)
+    schema = build_property(record.response_body, disposition: disposition, record: record, context: :response)
 
     # If examples are globally disabled, always return schema-only content.
     return { content_type => { schema: schema }.compact } unless example_enabled?(record)
@@ -121,7 +121,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
         name: build_parameter_name(key, value),
         in: 'path',
         required: true,
-        schema: build_property(try_cast(value), key: key, record: record),
+        schema: build_property(try_cast(value), key: key, record: record, path: key.to_s, context: :request),
         example: (try_cast(value) if example_enabled?(record)),
       }.compact
     end
@@ -131,7 +131,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
         name: key,
         in: 'query',
         required: record.required_request_params.include?(key),
-        schema: build_property(try_cast(value), key: key, record: record),
+        schema: build_property(try_cast(value), key: key, record: record, path: key.to_s, context: :request),
         example: (try_cast(value) if example_enabled?(record)),
       }.compact
     end
@@ -141,7 +141,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
         name: build_parameter_name(key, value),
         in: 'header',
         required: true,
-        schema: build_property(try_cast(value), key: key, record: record),
+        schema: build_property(try_cast(value), key: key, record: record, path: key.to_s, context: :request),
         example: (try_cast(value) if example_enabled?(record)),
       }.compact
     end
@@ -158,7 +158,7 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
 
     record.response_headers.each do |key, value|
       headers[key] = {
-        schema: build_property(try_cast(value), key: key, record: record),
+        schema: build_property(try_cast(value), key: key, record: record, path: key.to_s, context: :response),
       }.compact
     end
 
@@ -196,29 +196,31 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
     {
       content: {
         normalize_content_type(record.request_content_type) => {
-          schema: build_property(record.request_params, record: record),
+          schema: build_property(record.request_params, record: record, context: :request),
           example: (build_example(record.request_params) if example_enabled?(record)),
         }.compact,
       },
     }
   end
 
-  def build_property(value, disposition: nil, key: nil, record: nil)
+  def build_property(value, disposition: nil, key: nil, record: nil, path: nil, context: nil)
     format = disposition ? 'binary' : infer_format(key, record)
+    enum = infer_enum(path, record, context)
 
-    property = build_type(value, format: format)
+    property = build_type(value, format: format, enum: enum)
 
     case value
     when Array
       property[:items] = if value.empty?
                            {} # unknown
                          else
-                           build_array_items_schema(value, record: record)
+                           build_array_items_schema(value, record: record, path: path, context: context)
                          end
     when Hash
       property[:properties] = {}.tap do |properties|
-        value.each do |key, v|
-          properties[key] = build_property(v, record: record, key: key)
+        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)
@@ -226,29 +228,34 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
     property
   end
 
-  def build_type(value, format: nil)
-    return { type: 'string', format: format } if format
-
-    case value
-    when String
-      { type: 'string' }
-    when Integer
-      { type: 'integer' }
-    when Float
-      { type: 'number', format: 'float' }
-    when TrueClass, FalseClass
-      { type: 'boolean' }
-    when Array
-      { type: 'array' }
-    when Hash
-      { type: 'object' }
-    when ActionDispatch::Http::UploadedFile
-      { type: 'string', format: 'binary' }
-    when NilClass
-      { nullable: true }
-    else
-      raise NotImplementedError, "type detection is not implemented for: #{value.inspect}"
-    end
+  def build_type(value, format: nil, enum: nil)
+    result = if format
+               { type: 'string', format: format }
+             else
+               case value
+               when String
+                 { type: 'string' }
+               when Integer
+                 { type: 'integer' }
+               when Float
+                 { type: 'number', format: 'float' }
+               when TrueClass, FalseClass
+                 { type: 'boolean' }
+               when Array
+                 { type: 'array' }
+               when Hash
+                 { type: 'object' }
+               when ActionDispatch::Http::UploadedFile
+                 { type: 'string', format: 'binary' }
+               when NilClass
+                 { nullable: true }
+               else
+                 raise NotImplementedError, "type detection is not implemented for: #{value.inspect}"
+               end
+             end
+
+    result[:enum] = enum if enum
+    result
   end
 
   def infer_format(key, record)
@@ -257,6 +264,16 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
     record.formats[key]
   end
 
+  def infer_enum(path, record, context)
+    return nil if !path || !record
+
+    enum_hash = context == :request ? record.request_enum : record.response_enum
+    return nil unless enum_hash
+
+    # Try both string and symbol keys
+    enum_hash[path.to_s] || enum_hash[path.to_sym]
+  end
+
   # Convert an always-String param to an appropriate type
   def try_cast(value)
     Integer(value)
@@ -306,12 +323,12 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
     content_disposition&.sub(/;.+\z/, '')
   end
 
-  def build_array_items_schema(array, record: nil)
+  def build_array_items_schema(array, record: nil, path: nil, context: nil)
     return {} if array.empty?
-    return build_property(array.first, record: record) if array.size == 1
-    return build_property(array.first, record: record) unless array.all? { |item| item.is_a?(Hash) }
+    return build_property(array.first, record: record, path: path, context: context) if array.size == 1
+    return build_property(array.first, record: record, path: path, context: context) unless array.all? { |item| item.is_a?(Hash) }
 
-    all_schemas = array.map { |item| build_property(item, record: record) }
+    all_schemas = array.map { |item| build_property(item, record: record, path: path, context: context) }
     merged_schema = all_schemas.first.dup
     merged_schema[:properties] = {}
 

data/lib/rspec/openapi/schema_merger.rb

@@ -65,13 +65,61 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
 
     all_parameters = all_parameters.map do |parameter|
       base_parameter = unique_base_parameters[[parameter[:name], parameter[:in]]] || {}
-      base_parameter ? base_parameter.merge(parameter) : parameter
+      if base_parameter.empty?
+        parameter
+      else
+        merge_parameter_with_schema(base_parameter, parameter)
+      end
     end
 
     all_parameters.uniq! { |param| param.slice(:name, :in) }
     base[key] = all_parameters
   end
 
+  def merge_parameter_with_schema(base_param, new_param)
+    base_schema = base_param[:schema]
+    new_schema = new_param[:schema]
+
+    # If schemas have different types, create a oneOf
+    if base_schema && new_schema && schemas_have_different_types?(base_schema, new_schema)
+      merged_schema = merge_schemas_into_one_of(base_schema, new_schema)
+      base_param.merge(new_param).merge(schema: merged_schema)
+    else
+      base_param.merge(new_param)
+    end
+  end
+
+  def schemas_have_different_types?(schema1, schema2)
+    # If either already has oneOf, we need to merge into it
+    return true if schema1[:oneOf] || schema2[:oneOf]
+
+    type1 = schema1[:type]
+    type2 = schema2[:type]
+
+    type1 && type2 && type1 != type2
+  end
+
+  def merge_schemas_into_one_of(base_schema, new_schema)
+    existing_types = extract_schema_types(base_schema)
+    new_types = extract_schema_types(new_schema)
+
+    all_types = existing_types + new_types
+    all_types.uniq!
+
+    # If only one type remains, return it directly
+    return all_types.first if all_types.size == 1
+
+    { oneOf: all_types }
+  end
+
+  def extract_schema_types(schema)
+    if schema[:oneOf]
+      schema[:oneOf].map { |s| s.reject { |k, _| k == :example } }
+    else
+      [schema.reject { |k, _| k == :example }]
+    end
+  end
+
   def build_unique_params(base, key)
     base[key].each_with_object({}) do |parameter, hash|
       hash[[parameter[:name], parameter[:in]]] = parameter

data/lib/rspec/openapi/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module OpenAPI
-    VERSION = '0.23.0'
+    VERSION = '0.25.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-openapi
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.25.0
 platform: ruby
 authors:
 - Takashi Kokubun
@@ -112,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.23.0
+  changelog_uri: https://github.com/exoego/rspec-openapi/releases/tag/v0.25.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: