rspec-openapi 0.24.0 → 0.25.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df4214dc6ec5b88e9418ccc5e0c7cc86b69fbe90ec960faba1c48db8c5a5885d
-  data.tar.gz: f4de4de889d2e8df45173ce55c3e010e7838fa32b7f4af20435df7ba01b03868
+  metadata.gz: fdb09465b214320cfd32bf020363827d17c3346d48cb7e724effc99df6bdf722
+  data.tar.gz: 9947b0df4b2af301473ff89cd52cd035d8a4cb129bd83f8aacef2fc4df107cd5
 SHA512:
-  metadata.gz: 908be0ef51bad71044644c4e3abaf6dccf54d712f489963afd4b7e05a4cdbfdb6848536ed1aa9004e38bf1b85f0ebe79da365368a7f0559f291aa29416e54040
-  data.tar.gz: 542c5ed74819337e5cddcd244792aab84084afc9a43e81cb2b73e3bbb8eff9056ed3b62f5354d4421a6c3490e8356b16366b22da30c317989efcce757e77d714
+  metadata.gz: f17329553b8d2a02b196faba4ac592826557acb79648f364994614759e762608241d1310be6080873703af3b7f45d111db3509302f9ec22270c6c3c849bbd180
+  data.tar.gz: dd616bc6570e99d2b6439d4003bcadcdc9881613c6f4ba0428191ceef2c7c73dd185c5e385ea6c8af271f98d5c67d3e597062052d2c3bd7c59d1c0f6e75f0deb

data/.github/workflows/create_release.yml

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

data/.github/workflows/test.yml

@@ -42,7 +42,7 @@ jobs:
       - run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
         name: codecov-action@v4 workaround
       - name: Upload coverage reports
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         if: matrix.coverage == 'coverage'
         with:
           fail_ci_if_error: true

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/components_updater.rb

@@ -3,6 +3,8 @@
 require_relative 'hash_helper'
 
 class << RSpec::OpenAPI::ComponentsUpdater = Object.new
+  SCHEMA_REF_PREFIX = '#/components/schemas/'
+
   # @param [Hash] base
   # @param [Hash] fresh
   def update!(base, fresh)
@@ -30,7 +32,7 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
       # Skip if the property using $ref is not found in the parent schema. The property may be removed.
       next if nested_schema.nil?
 
-      schema_name = base.dig(*paths)&.gsub('#/components/schemas/', '')&.to_sym
+      schema_name = extract_schema_name(base.dig(*paths))&.to_sym
       fresh_schemas[schema_name] ||= {}
       RSpec::OpenAPI::SchemaMerger.merge!(fresh_schemas[schema_name], nested_schema)
     end
@@ -44,8 +46,8 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
   def build_fresh_schemas(references, base, fresh)
     references.inject({}) do |acc, paths|
       ref_link = dig_schema(base, paths)[:$ref]
-      schema_name = ref_link.to_s.gsub('#/components/schemas/', '')
-      schema_body = dig_schema(fresh, paths.reject { |path| path.is_a?(Integer) })
+      schema_name = extract_schema_name(ref_link)
+      schema_body = dig_schema(fresh, paths.grep_v(Integer))
 
       RSpec::OpenAPI::SchemaMerger.merge!(acc, { schema_name => schema_body })
     end
@@ -81,18 +83,29 @@ class << RSpec::OpenAPI::ComponentsUpdater = Object.new
     # Reject already-generated schemas to reduce unnecessary loop
     nested_refs.reject do |paths|
       ref_link = base.dig(*paths)
-      schema_name = ref_link.gsub('#/components/schemas/', '')
+      schema_name = extract_schema_name(ref_link)
       generated_names.include?(schema_name)
     end
   end
 
   def find_one_of_refs(base, paths)
-    dig_schema(base, paths)&.dig(:oneOf)&.map&.with_index do |schema, index|
-      paths + [index] if schema&.dig(:$ref)&.start_with?('#/components/schemas/')
-    end&.compact
+    one_of = dig_schema(base, paths)&.dig(:oneOf)
+    return unless one_of
+
+    one_of.each_with_index.filter_map do |schema, index|
+      paths + [index] if schema_ref?(schema&.dig(:$ref))
+    end
   end
 
   def find_object_refs(base, paths)
-    [paths] if dig_schema(base, paths)&.dig(:$ref)&.start_with?('#/components/schemas/')
+    [paths] if schema_ref?(dig_schema(base, paths)&.dig(:$ref))
+  end
+
+  def extract_schema_name(ref_link)
+    ref_link&.delete_prefix(SCHEMA_REF_PREFIX)
+  end
+
+  def schema_ref?(ref_link)
+    ref_link&.start_with?(SCHEMA_REF_PREFIX)
   end
 end

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

@@ -38,13 +38,11 @@ end
 InspectorAnalyzer = Inspector.new
 
 # Add default parameter to load inspector before test cases run
-module InspectorAnalyzerPrepender
+Hanami::Slice::ClassMethods.prepend(Module.new do
   def router(inspector: InspectorAnalyzer)
     super
   end
-end
-
-Hanami::Slice::ClassMethods.prepend(InspectorAnalyzerPrepender)
+end)
 
 # Extractor for hanami
 class << RSpec::OpenAPI::Extractors::Hanami = Object.new
@@ -57,17 +55,17 @@ 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
 
     raw_path_params = route.params
 
-    result = InspectorAnalyzer.call(request.method, add_id(path, route))
+    result = InspectorAnalyzer.call(request.method, replace_path_params(path, route, '/:%{key}'))
 
     summary ||= result[:summary]
     tags ||= result[:tags]
-    path = add_openapi_id(path, route)
+    path = replace_path_params(path, route, '/{%{key}}')
 
     raw_path_params = raw_path_params.slice(*(raw_path_params.keys - RSpec::OpenAPI.ignored_path_params))
 
@@ -85,6 +83,8 @@ class << RSpec::OpenAPI::Extractors::Hanami = Object.new
       example_mode,
       example_key,
       example_name,
+      response_enum,
+      request_enum,
     ]
   end
 
@@ -99,21 +99,11 @@ class << RSpec::OpenAPI::Extractors::Hanami = Object.new
 
   private
 
-  def add_id(path, route)
-    return path if route.params.empty?
-
-    route.params.each_pair do |key, value|
-      path = path.sub("/#{value}", "/:#{key}")
-    end
-
-    path
-  end
-
-  def add_openapi_id(path, route)
+  def replace_path_params(path, route, format)
     return path if route.params.empty?
 
     route.params.each_pair do |key, value|
-      path = path.sub("/#{value}", "/{#{key}}")
+      path = path.sub("/#{value}", format % { key: key })
     end
 
     path

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

@@ -12,8 +12,9 @@ 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, example_mode, example_key, example_name = 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, response_enum, request_enum = extractor.request_attributes(request, example)
 
     return if RSpec::OpenAPI.ignored_paths.any? { |ignored_path| path.match?(ignored_path) }
 
@@ -45,6 +46,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
+
+    # Keys are already normalized to strings by SharedExtractor.normalize_enum
+    enum_hash[path.to_s]
+  end
+
   # Convert an always-String param to an appropriate type
   def try_cast(value)
     Integer(value)
@@ -302,16 +319,15 @@ class << RSpec::OpenAPI::SchemaBuilder = Object.new
     content_type&.sub(/;.+\z/, '')
   end
 
-  def normalize_content_disposition(content_disposition)
-    content_disposition&.sub(/;.+\z/, '')
-  end
+  # Same logic as normalize_content_type – strips header parameters after ';'
+  alias normalize_content_disposition normalize_content_type
 
-  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?(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_cleaner.rb

@@ -70,6 +70,8 @@ class << RSpec::OpenAPI::SchemaCleaner = Object.new
     ]
     paths_to_objects.each do |path|
       parent = base.dig(*path.take(path.length - 1))
+      next unless parent
+
       # "required" array  must not be present if empty
       parent.delete(:required) if parent[:required] && parent[:required].empty?
     end

data/lib/rspec/openapi/schema_merger.rb

@@ -9,6 +9,8 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
     merge_schema!(base, spec)
   end
 
+  SIMILARITY_THRESHOLD = 0.5
+
   private
 
   # Not doing `base.replace(deep_merge(base, spec))` to preserve key orders.
@@ -121,13 +123,11 @@ class << RSpec::OpenAPI::SchemaMerger = Object.new
   end
 
   def build_unique_params(base, key)
-    base[key].each_with_object({}) do |parameter, hash|
-      hash[[parameter[:name], parameter[:in]]] = parameter
+    base[key].to_h do |parameter|
+      [[parameter[:name], parameter[:in]], parameter]
     end
   end
 
-  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)

data/lib/rspec/openapi/version.rb

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

data/lib/rspec/openapi.rb

@@ -33,7 +33,7 @@ module RSpec::OpenAPI
   @comment = nil
   @enable_example = true
   @enable_example_summary = true
-  @description_builder = ->(example) { example.description }
+  @description_builder = :description.to_proc
   @example_name_builder = :description.to_proc
   @summary_builder = ->(example) { example.metadata[:summary] }
   @tags_builder = ->(example) { example.metadata[:tags] }

data/rspec-openapi.gemspec

@@ -31,5 +31,4 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'actionpack', '>= 5.2.0'
   spec.add_dependency 'rails-dom-testing'
   spec.add_dependency 'rspec-core'
-  spec.metadata['rubygems_mfa_required'] = 'true'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-openapi
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.25.1
 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.24.0
+  changelog_uri: https://github.com/exoego/rspec-openapi/releases/tag/v0.25.1
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -128,7 +128,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Generate OpenAPI schema from RSpec request specs
 test_files: []