rspec-openapi 0.28.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43c486a798aeae6de0f9ecbec34ab2b69a11bb2b1ff053011110c611e5151fc0
-  data.tar.gz: f483a6aca96935df40e9b34386b34548f3322982935c3801bab33ee72d20746e
+  metadata.gz: 97857dc0658df5323bf3997e3acc31cf8f8b2f713a2d2ec6e3fdb0be7661aaf5
+  data.tar.gz: 9ecdb6c88c4c58042f805d899cda3d50fe2b670286de4d7f64b3799fd1ee5d48
 SHA512:
-  metadata.gz: 7860f7a5030487e9671ee926bcf27967c827a4d80f6119eca70c8e9b330c296a5813bc8412d3b210e679700baef2d8710bcd9c9ca24c8b5890a14d90823f8c36
-  data.tar.gz: c2d9e3aaab37b25acc4d1ce563076a2fcb151f33a699268d9035d1559b428f75a75dab52394d0810a0443f031e9f3f338e9996320e5c258b598d0262a71bf1a0
+  metadata.gz: 14577c70d8caca9754f4893be1720ed67dbb4762f1479a4454e188cc954ba8e9651f887cc0c69a95c91c1c98f994739bf12667f7470a491b60f9f2ce21ac81fc
+  data.tar.gz: feb18e9c32bed1f101dca61683e30975857257999fac322ff9ed51519a7ac13d583ad1cf68b3f20c56782919c9bb2d6d83d94396204c3287c468c692b1b121e1

data/README.md

@@ -116,6 +116,10 @@ RSpec::OpenAPI.path = 'doc/schema.yaml'
 # Change the output type to JSON
 RSpec::OpenAPI.path = 'doc/schema.json'
 
+# Or emit the same schema in multiple formats from a single run by passing an array.
+# The output format of each file is still chosen by its extension (`.json` -> JSON, otherwise YAML).
+RSpec::OpenAPI.path = ['doc/openapi.yaml', 'doc/openapi.json']
+
 # Or generate multiple partial schema files, given an RSpec example
 RSpec::OpenAPI.path = -> (example) {
   case example.file_path
@@ -125,6 +129,12 @@ RSpec::OpenAPI.path = -> (example) {
   end
 }
 
+# The two can be combined: a proc may also return an array to fan a partial schema out to multiple formats.
+RSpec::OpenAPI.path = -> (example) {
+  base = example.file_path.match?(%r[spec/requests/api/v2/]) ? 'doc/openapi/v2' : 'doc/openapi'
+  ["#{base}.yaml", "#{base}.json"]
+}
+
 # Change the default title of the generated schema
 RSpec::OpenAPI.title = 'OpenAPI Documentation'
 
@@ -190,10 +200,16 @@ RSpec::OpenAPI.description_builder = -> (example) { example.description }
 
 # Generate a custom summary, given an RSpec example
 # This example uses the summary from the example_group.
+# NOTE: a fixed `dig` only reaches one specific depth. `summary` declared on an
+# ancestor group is already inherited automatically (see "Inheritance of
+# `openapi:` metadata"), so a builder is only needed for fully custom logic.
 RSpec::OpenAPI.summary_builder = ->(example) { example.metadata.dig(:example_group, :openapi, :summary) }
 
 # Generate a custom tags, given an RSpec example
-# This example uses the tags from the parent_example_group
+# This example uses the tags from the parent_example_group.
+# NOTE: `dig(:example_group, :parent_example_group, ...)` only matches tags
+# declared exactly two levels up; it won't find tags on deeper ancestors. Rely
+# on the built-in inheritance unless you need custom resolution.
 RSpec::OpenAPI.tags_builder = -> (example) { example.metadata.dig(:example_group, :parent_example_group, :openapi, :tags) }
 
 # Configure custom format for specific properties
@@ -369,6 +385,26 @@ end
 
 **NOTE**: `description` key will override also the one provided by `RSpec::OpenAPI.description_builder` method.
 
+### Inheritance of `openapi:` metadata
+
+`openapi:` metadata is inherited from the surrounding `describe`/`context` groups down to each
+example, at any nesting depth. Inner levels override outer ones key by key, so a nested group only
+needs to declare the keys it wants to change:
+
+```rb
+describe 'GET /tables', openapi: { summary: 'Get a list of tables', tags: %w[Table] } do
+  context 'with pagination', openapi: { example_mode: :multiple } do
+    # This example inherits summary: 'Get a list of tables' and tags: ['Table']
+    # from the outer describe, and adds example_mode: :multiple.
+    it { get '/tables', params: { page: 1 } }
+  end
+end
+```
+
+The merge happens at the top level of the `openapi:` hash. Scalar keys (`summary`, `operation_id`,
+…) follow last-wins, and a nested level that re-declares a structured key (`tags`, `security`,
+`enum`, …) replaces the inherited value for that key rather than deep-merging it.
+
 ### Enum Support
 
 You can specify enum values for string properties that should have a fixed set of allowed values. Since enums cannot be

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

@@ -86,14 +86,12 @@ class SharedExtractor
 
   def self.collect_openapi_metadata(metadata)
     [].tap do |result|
-      current = metadata
+      result.unshift(metadata[:openapi]) if metadata[:openapi]
 
-      while current
-        [current[:example_group], current].each do |meta|
-          result.unshift(meta[:openapi]) if meta&.dig(:openapi)
-        end
-
-        current = current[:parent_example_group]
+      group = metadata.fetch(:example_group) { metadata[:parent_example_group] }
+      while group
+        result.unshift(group[:openapi]) if group[:openapi]
+        group = group[:parent_example_group]
       end
     end
   end

data/lib/rspec/openapi/record_builder.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'logger'
 require 'action_dispatch'
 require 'rspec/openapi/record'
 

data/lib/rspec/openapi/result_recorder.rb

@@ -7,31 +7,16 @@ class RSpec::OpenAPI::ResultRecorder
   end
 
   def record_results!
-    @path_records.each do |path, records|
-      # Look for a path-specific config file and run it.
-      config_file = File.join(File.dirname(path), RSpec::OpenAPI.config_filename)
-      begin
-        require config_file if File.exist?(config_file)
-      rescue StandardError => e
-        puts "WARNING: Unable to load #{config_file}: #{e}"
-      end
+    @path_records.each do |paths, records|
+      # A single record set may target multiple output files (e.g. both YAML and
+      # JSON). The first path is the canonical source we read/merge into; the rest
+      # mirror the same built spec, each formatted by its own extension.
+      primary, *mirrors = Array(paths)
+      next if primary.nil?
 
-      title = records.first.title
-      RSpec::OpenAPI::SchemaFile.new(path).edit do |spec|
-        schema = RSpec::OpenAPI::DefaultSchema.build(title)
-        schema[:info].merge!(RSpec::OpenAPI.info)
-        RSpec::OpenAPI::SchemaMerger.merge!(spec, schema)
-        new_from_zero = {}
-        records.each do |record|
-          record_schema = RSpec::OpenAPI::SchemaBuilder.build(record)
-          RSpec::OpenAPI::SchemaMerger.merge!(spec, record_schema)
-          RSpec::OpenAPI::SchemaMerger.merge!(new_from_zero, record_schema)
-        rescue StandardError, NotImplementedError => e # e.g. SchemaBuilder raises a NotImplementedError
-          @error_records[e] = record # Avoid failing the build
-        end
-        cleanup_schema!(new_from_zero, spec)
-        execute_post_process_hook(path, records, spec)
-      end
+      load_path_config(primary)
+      built_spec = build_spec(primary, records)
+      mirrors.each { |mirror_path| RSpec::OpenAPI::SchemaFile.new(mirror_path).write(built_spec) }
     end
   end
 
@@ -49,6 +34,33 @@ class RSpec::OpenAPI::ResultRecorder
 
   private
 
+  # Look for a path-specific config file and run it.
+  def load_path_config(path)
+    config_file = File.join(File.dirname(path), RSpec::OpenAPI.config_filename)
+    require config_file if File.exist?(config_file)
+  rescue StandardError => e
+    puts "WARNING: Unable to load #{config_file}: #{e}"
+  end
+
+  def build_spec(primary, records)
+    title = records.first.title
+    RSpec::OpenAPI::SchemaFile.new(primary).edit do |spec|
+      schema = RSpec::OpenAPI::DefaultSchema.build(title)
+      schema[:info].merge!(RSpec::OpenAPI.info)
+      RSpec::OpenAPI::SchemaMerger.merge!(spec, schema)
+      new_from_zero = {}
+      records.each do |record|
+        record_schema = RSpec::OpenAPI::SchemaBuilder.build(record)
+        RSpec::OpenAPI::SchemaMerger.merge!(spec, record_schema)
+        RSpec::OpenAPI::SchemaMerger.merge!(new_from_zero, record_schema)
+      rescue StandardError, NotImplementedError => e # e.g. SchemaBuilder raises a NotImplementedError
+        @error_records[e] = record # Avoid failing the build
+      end
+      cleanup_schema!(new_from_zero, spec)
+      execute_post_process_hook(primary, records, spec)
+    end
+  end
+
   def execute_post_process_hook(path, records, spec)
     RSpec::OpenAPI.post_process_hook.call(path, records, spec) if RSpec::OpenAPI.post_process_hook.is_a?(Proc)
   end

data/lib/rspec/openapi/schema_file.rb

@@ -14,11 +14,30 @@ class RSpec::OpenAPI::SchemaFile
     @path = path
   end
 
+  # Reads the existing spec, lets the block mutate it, writes the result back
+  # and returns the (symbolized) spec so it can be mirrored to other files.
+  # @return [Hash]
   def edit(&block)
     spec = read
     block.call(spec)
+    spec
   ensure
-    write(RSpec::OpenAPI::KeyTransformer.stringify(spec))
+    write(spec)
+  end
+
+  # Writes an already-built spec to this file, choosing the format from the
+  # file extension.
+  # @param [Hash] spec
+  def write(spec)
+    stringified = RSpec::OpenAPI::KeyTransformer.stringify(spec)
+    FileUtils.mkdir_p(File.dirname(@path))
+    output =
+      if json?
+        JSON.pretty_generate(stringified)
+      else
+        prepend_comment(YAML.dump(stringified))
+      end
+    File.write(@path, output)
   end
 
   private
@@ -33,18 +52,6 @@ class RSpec::OpenAPI::SchemaFile
     RSpec::OpenAPI::KeyTransformer.symbolize(content)
   end
 
-  # @param [Hash] spec
-  def write(spec)
-    FileUtils.mkdir_p(File.dirname(@path))
-    output =
-      if json?
-        JSON.pretty_generate(spec)
-      else
-        prepend_comment(YAML.dump(spec))
-      end
-    File.write(@path, output)
-  end
-
   def prepend_comment(content)
     return content if RSpec::OpenAPI.comment.nil?
 

data/lib/rspec/openapi/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module OpenAPI
-    VERSION = '0.28.0'
+    VERSION = '0.29.0'
   end
 end

metadata

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