openapi-sourcetools 0.9.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 625fca7f208b4a1e4c041265a1b5aba0d0685bbda6dcdd831af5db701aff4de0
-  data.tar.gz: bfe98b2ef3fa42ca2edccdf7b57eda9d653637e23a6b6325e41297e00100e1b6
+  metadata.gz: 2b790daa9dc40626f360f32ba98853c2b5410e5214d0d2ef32334df1858a9262
+  data.tar.gz: 842e1b54d72995112b38f678f3b0f853d9e0e6ea03652d56797715cb215e2c35
 SHA512:
-  metadata.gz: 7895833d61f1954c4d6b056e2b350c72d767c7ec031222bcec9f8aa2820836eced6e5432f14465f567967bce674006e699bc65180d73951a1ff63b7d40c5fc57
-  data.tar.gz: b86546e0d0cf07d19ba082e43f29b4f0c35bef6d05f6e678695f7d821bf38e1e761eaa95ecf10a7c0a00e0a41710fdf088eba13b8c3bd9f4b46a7bac7db49f49
+  metadata.gz: 5fa1f5ac001251e2d5b56b701bac7d8489efd01fdbbfc2884a0be84c7c5f86dd1a85d1e1cff6120ae09d0d462912711a70ad269d2c5c740c4639a6e495057e78
+  data.tar.gz: ec9dc7d99bfcd12387d163a88c7502052c44cc0159c7bd5865d86a17af0511e979224289ec56f7f049400f4280e02fa583498a553791be9f1b762153cac4b903

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2021-2024 Ismo Kärkkäinen
+Copyright (c) 2021-2026 Ismo Kärkkäinen
 
 The Universal Permissive License (UPL), Version 1.0
 

data/bin/openapi-addheaders

@@ -1,37 +1,21 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Copyright © 2024-2025 Ismo Kärkkäinen
+# Copyright © 2024-2026 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
 require_relative '../lib/openapi/sourcetools/apiobjects'
 require_relative '../lib/openapi/sourcetools/common'
 require 'optparse'
 require 'yaml'
-include OpenAPISourceTools
 
 
-def replace_headers(obj, components)
-  return unless obj.is_a?(Hash)
-  obj.each do |k, v|
-    if k == 'headers'
-      v.keys.sort!.each do |name|
-        r = v[name]
-        next unless r.is_a?(Hash) # Could complain.
-        next if r.key?('$ref')
-        v[name] = { '$ref' => components.reference(r) }
-      end
-    else
-      replace_headers(v, components)
-    end
-  end
-end
-
 def main
   input_name = nil
   output_name = nil
   path = %w[components headers]
-  components = ApiObjects::Components.new(path, 'Header')
+  components = OpenAPISourceTools::ApiObjects::Components.new(path, 'Header')
+  replacer = OpenAPISourceTools::ApiObjects::ValueSubValueReplacer.new('headers', components)
 
   parser = OptionParser.new do |opts|
     opts.summary_indent = '  '
@@ -59,15 +43,15 @@ replaces the original with reference.
   end
   parser.order!
 
-  doc = Common.load_source(input_name)
+  doc = OpenAPISourceTools::Common.load_source(input_name)
   return 2 if doc.nil?
 
   components.items = doc.dig(*path) || {}
-  replace_headers(doc.dig('components', 'responses') || {}, components)
-  replace_headers(doc.fetch('paths', {}), components)
-  Common.bury(doc, path, components.items) unless components.items.empty?
+  replacer.replace(doc.dig('components', 'responses') || {})
+  replacer.replace(doc.fetch('paths', {}))
+  OpenAPISourceTools::Common.bury(doc, path, components.items) unless components.items.empty?
 
-  Common.dump_result(output_name, doc, 3)
+  OpenAPISourceTools::Common.dump_result(output_name, doc, 3)
 end
 
-exit(main) if defined?($unit_test).nil?
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-addparameters

@@ -1,18 +1,18 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Copyright © 2024-2025 Ismo Kärkkäinen
+# Copyright © 2024-2026 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
 require_relative '../lib/openapi/sourcetools/apiobjects'
 require_relative '../lib/openapi/sourcetools/common'
 require 'optparse'
-include OpenAPISourceTools
+
 
 def replace_parameter(p, components)
   return p unless p.is_a?(Hash) # Could complain.
   return p if p.key?('$ref')
-  { '$ref' => components.reference(p) }
+  components.to_reference_object(p)
 end
 
 def replace_parameters(obj, components)
@@ -46,7 +46,7 @@ def add_operations_parameters(paths, referenced)
   # Below that are operations objects.
   paths.each_value do |item|
     top_nameloc2ref = nameloc2ref(item['parameters'] || [], referenced)
-    oos = ApiObjects.operation_objects(item)
+    oos = OpenAPISourceTools::ApiObjects.operation_objects(item)
     oos.each_value do |operation|
       nl2r = nameloc2ref(operation['parameters'] || [], referenced)
       params = top_nameloc2ref.merge(nl2r)
@@ -61,7 +61,7 @@ def main
   output_name = nil
   add2operations = false
   path = %w[components parameters]
-  components = ApiObjects::Components.new(path, 'Parameter')
+  components = OpenAPISourceTools::ApiObjects::Components.new(path, 'Parameter')
 
   parser = OptionParser.new do |opts|
     opts.summary_indent = '  '
@@ -87,7 +87,8 @@ replaces the original with reference.
 
 Optionally adds parameters to all operations objects by copying parameters
 from path item and replacing ones referred to in operations object. The
-path item parameters are left in place. Even empty arrays are added.
+path item parameters are left in place. Even empty arrays are added. This
+feature is intended to simplify code generation.
 
 #{components.help}
 )
@@ -96,17 +97,17 @@ path item parameters are left in place. Even empty arrays are added.
   end
   parser.order!
 
-  doc = Common.load_source(input_name)
+  doc = OpenAPISourceTools::Common.load_source(input_name)
   return 2 if doc.nil?
 
   components.items = doc.dig(*path) || {}
   replace_parameters(doc.fetch('paths', {}), components)
-  Common.bury(doc, path, components.items) unless components.items.empty?
+  OpenAPISourceTools::Common.bury(doc, path, components.items) unless components.items.empty?
   # If nothing has parameters, this adds empty arrays.
   # Consistency might be desired for code generation templates.
   add_operations_parameters(doc.fetch('paths', {}), components.items) if add2operations
 
-  Common.dump_result(output_name, doc, 3)
+  OpenAPISourceTools::Common.dump_result(output_name, doc, 3)
 end
 
-exit(main) unless defined?($unit_test)
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-addresponses

@@ -1,36 +1,20 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Copyright © 2024-2025 Ismo Kärkkäinen
+# Copyright © 2024-2026 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
 require_relative '../lib/openapi/sourcetools/apiobjects'
 require_relative '../lib/openapi/sourcetools/common'
 require 'optparse'
-include OpenAPISourceTools
 
 
-def replace_responses(obj, components)
-  return unless obj.is_a?(Hash)
-  obj.each do |k, v|
-    if k == 'responses'
-      v.keys.sort!.each do |code|
-        r = v[code]
-        next unless r.is_a?(Hash) # Could complain.
-        next if r.key?('$ref')
-        v[code] = { '$ref' => components.reference(r) }
-      end
-    else
-      replace_responses(v, components)
-    end
-  end
-end
-
 def main
   input_name = nil
   output_name = nil
   path = %w[components responses]
-  components = ApiObjects::Components.new(path, 'Response')
+  components = OpenAPISourceTools::ApiObjects::Components.new(path, 'Response')
+  replacer = OpenAPISourceTools::ApiObjects::ValueSubValueReplacer.new('responses', components)
 
   parser = OptionParser.new do |opts|
     opts.summary_indent = '  '
@@ -58,14 +42,14 @@ replaces the original with reference.
   end
   parser.order!
 
-  doc = Common.load_source(input_name)
+  doc = OpenAPISourceTools::Common.load_source(input_name)
   return 2 if doc.nil?
 
   components.items = doc.dig(*path) || {}
-  replace_responses(doc.fetch('paths', {}), components)
-  Common.bury(doc, path, components.items) unless components.items.empty?
+  replacer.replace(doc.fetch('paths', {}))
+  OpenAPISourceTools::Common.bury(doc, path, components.items) unless components.items.empty?
 
-  Common.dump_result(output_name, doc, 3)
+  OpenAPISourceTools::Common.dump_result(output_name, doc, 3)
 end
 
-exit(main) if defined?($unit_test).nil?
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-addschemas

@@ -1,13 +1,12 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Copyright © 2024-2025 Ismo Kärkkäinen
+# Copyright © 2024-2026 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
 require_relative '../lib/openapi/sourcetools/apiobjects'
 require_relative '../lib/openapi/sourcetools/common'
 require 'optparse'
-include OpenAPISourceTools
 
 
 def remove_subitem(obj, path)
@@ -27,7 +26,6 @@ def replace_inlines(obj, components, top_level_name = nil)
   return true unless obj.is_a?(Hash)
   if obj.key?('$ref')
     components.store_anchor(obj)
-    # Here would be the place to get rid of other keys if so desired.
     return true
   end
   # Is inlined, process parts recursively.
@@ -58,7 +56,7 @@ def replace_inlines(obj, components, top_level_name = nil)
   end
   r = components.ref_string(top_level_name) || components.reference(obj)
   components.store_anchor(obj, r)
-  obj.replace({ '$ref' => r }) if top_level_name.nil?
+  components.to_reference_object(obj, r) if top_level_name.nil?
   true
 end
 
@@ -82,7 +80,7 @@ def main
   input_name = nil
   output_name = nil
   path = %w[components schemas]
-  components = ApiObjects::Components.new(path, 'Schema')
+  components = OpenAPISourceTools::ApiObjects::Components.new(path, 'Schema')
 
   parser = OptionParser.new do |opts|
     opts.summary_indent = '  '
@@ -109,7 +107,7 @@ Loads API document in OpenAPI format and adds a schema for each inline type.
   end
   parser.order!
 
-  doc = Common.load_source(input_name)
+  doc = OpenAPISourceTools::Common.load_source(input_name)
   return 2 if doc.nil?
 
   # Find schema object and remove it temporarily to prevent being
@@ -122,10 +120,10 @@ Loads API document in OpenAPI format and adds a schema for each inline type.
   end
   return 4 unless replace_inlines(doc, components)
   components.alter_anchors
-  Common.bury(doc, path, components.items) unless components.items.empty?
+  OpenAPISourceTools::Common.bury(doc, path, components.items) unless components.items.empty?
   replace_anchor_refs(doc, components)
 
-  Common.dump_result(output_name, doc, 3)
+  OpenAPISourceTools::Common.dump_result(output_name, doc, 3)
 end
 
-exit(main) if defined?($unit_test).nil?
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-addsecurityschemes

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Copyright © 2025 Ismo Kärkkäinen
+# Copyright © 2025-2026 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
 require_relative '../lib/openapi/sourcetools/apiobjects'
@@ -105,4 +105,4 @@ replaces the original with reference.
   Common.dump_result(output_name, doc, 3)
 end
 
-exit(main) unless defined?($unit_test)
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-checkschemas

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Copyright © 2024-2025 Ismo Kärkkäinen
+# Copyright © 2024-2026 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
 require_relative '../lib/openapi/sourcetools/apiobjects'
@@ -214,4 +214,4 @@ input, as inlined types in requests, for example, are ignored.
   Common.dump_result(output_name, YAML.dump(report, line_width: 80), 3)
 end
 
-exit(main) if defined?($unit_test).nil?
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-clearrefs

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2026 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative '../lib/openapi/sourcetools/apiobjects'
+require_relative '../lib/openapi/sourcetools/common'
+require 'optparse'
+require 'yaml'
+
+
+def main
+  input_name = nil
+  output_name = nil
+  retainer = OpenAPISourceTools::ApiObjects::ValueRetainer.new('$ref')
+
+  parser = OptionParser.new do |opts|
+    opts.summary_indent = '  '
+    opts.summary_width = 26
+    opts.banner = 'Usage: openapi-clearrefs [options]'
+    opts.separator ''
+    opts.separator 'Options:'
+    opts.on('-i', '--input FILE', 'Read API spec from FILE, not stdin.') do |f|
+      input_name = f
+    end
+    opts.on('-o', '--output FILE', 'Output to FILE, not stdout.') do |f|
+      output_name = f
+    end
+    opts.on('-h', '--help', 'Print this help and exit.') do
+      $stdout.puts %(#{opts}
+Loads API document in OpenAPI format and from objects with '$ref' key, deletes
+all other keys.
+)
+      exit 0
+    end
+  end
+  parser.order!
+
+  doc = OpenAPISourceTools::Common.load_source(input_name)
+  return 2 if doc.nil?
+  retainer.process(doc)
+  OpenAPISourceTools::Common.dump_result(output_name, doc, 3)
+end
+
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-frequencies

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Copyright © 2021-2025 Ismo Kärkkäinen
+# Copyright © 2021-2026 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
 require_relative '../lib/openapi/sourcetools/apiobjects'
@@ -73,4 +73,4 @@ into each path object matching count as "x-openapi-sourcetools-freq".
   Common.dump_result(output_name, doc, 3)
 end
 
-exit(main) unless defined?($unit_test)
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-generate

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Copyright © 2021-2025 Ismo Kärkkäinen
+# Copyright © 2021-2026 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
 require_relative '../lib/openapi/sourcetools/common'
@@ -58,4 +58,4 @@ After all generators have loaded succesfully, tasks are run.
   gen.run
 end
 
-exit(main) unless defined?($unit_test)
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-merge

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Copyright © 2021-2025 Ismo Kärkkäinen
+# Copyright © 2021-2026 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
 require_relative '../lib/openapi/sourcetools/common'
@@ -34,18 +34,23 @@ def add_missing(existing, incoming, field)
   end
 end
 
-def add_undefined(merged, incoming, filename, path, max_depths)
+def add_undefined(merged, incoming, filename, path, max_depths, firsts, lasts)
   incoming.each_pair do |key, value|
     unless merged.key? key
       merged[key] = value
       next
     end
+    next if firsts.member?(key) # When key appears the second or more times.
+    if lasts.member?(key) # If last is kept, always copy value.
+      merged[key] = value
+      next
+    end
     m = merged[key]
     raise_se("Path #{path_combo(path, false)} merged type #{m.class} differs from type #{value.class} in #{filename}") unless m.instance_of?(value.class)
     raise_se("Re-definition of #{key} #{path_combo(path)} in #{filename}") if too_deep(path, max_depths)
     if m.is_a? Hash # paths or similar
       path.push key
-      add_undefined(m, value, filename, path, max_depths)
+      add_undefined(m, value, filename, path, max_depths, firsts, lasts)
       path.pop
     elsif m.is_a? Array
       case key
@@ -121,6 +126,8 @@ end
 def main
   output_file = nil
   keep = false
+  firsts = Set.new
+  lasts = Set.new
 
   parser = OptionParser.new do |opts|
     opts.summary_indent = '  '
@@ -137,6 +144,12 @@ def main
     opts.on('-p', '--prune', 'Prune all unreferenced objects under components (default).') do
       keep = false
     end
+    opts.on('-f', '--first KEY', 'Keep only the first occurrence of top-level KEY.') do |key|
+      firsts.add(key)
+    end
+    opts.on('-l', '--last KEY', 'Keep only the last occurrence of top-level KEY.') do |key|
+      lasts.add(key)
+    end
     opts.on('-h', '--help', 'Print this help and exit.') do
       $stdout.puts %(#{opts}
 
@@ -148,20 +161,27 @@ allowed only to append to the merged document, not re-define anything in it.
   end
   parser.order!
 
-  max_depths = Hash.new(0)
-  max_depths['openapi'] = 1
-  max_depths['info'] = 1
-  max_depths['servers'] = 1
-  max_depths['paths'] = 2 # Allows get, post, etc. from different files.
-  max_depths['webhooks'] = 2
-  max_depths['components'] = 2
-  max_depths['security'] = 1
-  max_depths['tags'] = 1
+  overlap = firsts & lasts
+  unless overlap.empty?
+    return Common.aargh("Key can only be in first or last, not both: #{overlap.to_a.sort!.join(' ')}", 1)
+  end
+
+  max_depths = Hash.new(0).merge!({
+    'openapi' => 1,
+    'info' => 1,
+    'servers' => 1,
+    'paths' => 2, # Allows get, post, etc. from different files.
+    'webhooks' => 2,
+    'components' => 2,
+    'security' => 1,
+    'tags' => 1
+  })
+
   merged = {}
   ARGV.each do |filename|
     s = Common.load_source(filename)
     return 2 if s.nil?
-    add_undefined(merged, s, filename, [], max_depths)
+    add_undefined(merged, s, filename, [], max_depths, firsts, lasts)
   rescue StandardError => e
     return Common.aargh(e.to_s, 4)
   end
@@ -171,4 +191,4 @@ allowed only to append to the merged document, not re-define anything in it.
   Common.dump_result(output_file, merged, 3)
 end
 
-exit(main) if defined?($unit_test).nil?
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-modifypaths

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Copyright © 2024-2025 Ismo Kärkkäinen
+# Copyright © 2024-2026 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
 require_relative '../lib/openapi/sourcetools/common'
@@ -121,4 +121,4 @@ STR and PREFIX are expected to be parts of a path surrounded by /.
   Common.dump_result(output_name, doc, 3)
 end
 
-exit(main) if defined?($unit_test).nil?
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-patterntests

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Copyright © 2025 Ismo Kärkkäinen
+# Copyright © 2025-2026 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
 require_relative '../lib/openapi/sourcetools/common'
@@ -163,4 +163,4 @@ strings for testing generated code.
   Common.dump_result(output_name, ex, 3)
 end
 
-exit(main) if defined?($unit_test).nil?
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-processpaths

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Copyright © 2021-2025 Ismo Kärkkäinen
+# Copyright © 2021-2026 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
 require_relative '../lib/openapi/sourcetools/apiobjects'
@@ -70,4 +70,4 @@ key. Checks for paths that may be ambiguous.
   Common.dump_result(output_name, doc, 3)
 end
 
-exit(main) unless defined?($unit_test)
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/lib/openapi/sourcetools/apiobjects.rb

@@ -37,10 +37,99 @@ module OpenAPISourceTools
       end
     end
 
+    # Any value with given key has all but retained keys removed.
+    class ValueRetainer
+      attr_reader :key
+      attr_accessor :retain
+
+      def initialize(trigger_key)
+        @key = trigger_key
+        @retain = [ trigger_key ]
+      end
+
+      def process(obj)
+        if obj.is_a?(Array)
+          obj.each { |item| process(item) }
+          return
+        end
+        return unless obj.is_a?(Hash)
+        if obj.key?(@key)
+          obj.delete_if { |k, _v| !@retain.include?(k) }
+        end
+        obj.each_value do |value|
+          process(value)
+        end
+      end
+    end
+
+    # A replacer for value of a given key.
+    class ValueReplacer
+      attr_reader :key, :components
+
+      def initialize(trigger_key, components)
+        @key = trigger_key
+        @components = components
+      end
+
+      def replace(obj)
+        if obj.is_a?(Array)
+          obj.each { |item| replace(item) }
+          return
+        end
+        return unless obj.is_a?(Hash)
+        obj.each do |key, value|
+          if key == @key
+            if value.is_a?(Array)
+              value.each do |item|
+                next unless item.is_a?(Hash)
+                next if item.key?('$ref')
+                @components.to_reference_object(item)
+              end
+            elsif value.is_a?(Hash)
+              next if value.key?('$ref')
+              @components.to_reference_object(value)
+            end
+          else
+            replace(value)
+          end
+        end
+      end
+    end
+
+    # A replacer for sub-values of a value of a given key.
+    class ValueSubValueReplacer
+      attr_reader :key, :components
+
+      def initialize(trigger_key, components)
+        @key = trigger_key
+        @components = components
+      end
+
+      def replace(obj)
+        if obj.is_a?(Array)
+          obj.each { |item| replace(item) }
+          return
+        end
+        return unless obj.is_a?(Hash)
+        obj.each do |key, value|
+          if key == @key && value.is_a?(Hash)
+            value.keys.sort!.each do |sub_key|
+              sub_value = value[sub_key]
+              next unless sub_value.is_a?(Hash)
+              next if sub_value.key?('$ref')
+              @components.to_reference_object(value[sub_key])
+            end
+          else
+            replace(value)
+          end
+        end
+      end
+    end
+
     # A component in the API specification for reference and anchor handling.
     class Components
       attr_reader :path, :prefix, :anchor2ref, :schema_names
-      attr_accessor :items, :ignored_keys
+      attr_accessor :items, :ignored_keys, :retain_ignored
 
       def initialize(path, prefix, ignored_keys = %w[summary description examples example $anchor])
         path = "#/#{path.join('/')}/" if path.is_a?(Array)
@@ -51,6 +140,7 @@ module OpenAPISourceTools
         @schema_names = Set.new
         @items = {}
         @ignored_keys = Set.new(ignored_keys)
+        @retain_ignored = false
       end
 
       def add_options(opts)
@@ -60,6 +150,9 @@ module OpenAPISourceTools
         opts.on('--ignore FIELD', 'Ignore FIELD in comparisons.') do |f|
           @ignored_keys.add(f)
         end
+        opts.on('--retain-ignored', 'Retain ignored fields in reference object.') do
+          @retain_ignored = true
+        end
       end
 
       def help
@@ -91,6 +184,17 @@ module OpenAPISourceTools
         end
       end
 
+      def to_reference_object(obj, ref = nil)
+        ref = reference(obj) if ref.nil?
+        if @retain_ignored
+          obj.delete_if { |k, _v| !@ignored_keys.member?(k) }
+        else
+          obj.clear
+        end
+        obj['$ref'] = ref
+        obj
+      end
+
       def store_anchor(obj, ref = nil)
         anchor_name = obj['$anchor']
         return if anchor_name.nil?
@@ -251,5 +355,83 @@ module OpenAPISourceTools
         @servers <=> other.servers
       end
     end
+
+    # Simple holder if security scheme objects.
+    class SecurityScheme
+      include Comparable
+
+      attr_reader :name, :scheme
+
+      def initialize(name, scheme)
+        @name = name
+        @scheme = scheme
+      end
+
+      def <=>(other)
+        @name <=> other.name
+      end
+    end
+
+    # Simple holder that determines where parameters are placed.
+    class SecurityRequirementObject
+      include Comparable
+
+      attr_reader :reqs, :extras
+
+      def initialize(reqs, schemes)
+        @reqs = reqs
+        @extras = {}
+        @reqs.each do |name, scopes|
+          scheme = schemes[name].scheme
+          case scheme['type']
+          when 'apiKey'
+            if scheme['in'] == 'header'
+              h = @extras[:headers] || {}
+              h[scheme['name']] = scopes
+              @extras[:headers] = h
+            elsif scheme['in'] == 'query'
+              q = @extras[:query] || {}
+              q[scheme['name']] = scopes
+              @extras[:query] = q
+            end
+          when 'http', 'oauth2', 'openIdConnect'
+            h = @extras[:headers] || {}
+            h['authorization'] = scopes
+            @extras[:headers] = h
+          else
+            raise "Unknown security type: #{scheme['type']} for #{name}"
+          end
+        end
+      end
+
+      def <=>(other)
+        d = @reqs.size <=> other.reqs.size
+        return d unless d.zero?
+        d = @reqs.keys.sort! <=> other.reqs.keys.sort!
+        return d unless d.zero?
+        @reqs.keys.sort!.each do |name|
+          d = @reqs[name].sort <=> other.reqs[name].sort
+          return d unless d.zero?
+        end
+        0
+      end
+    end
+
+    # Available possibilities.
+    class SecurityAlternatives
+      include Comparable
+
+      attr_reader :sros, :schemes
+      attr_accessor :set_id
+
+      def initialize(sros, schemes)
+        @sros = sros
+        @schemes = schemes
+      end
+
+      def <=>(other)
+        @sros.sort <=> other.sros.sort
+      end
+    end
   end
 end

data/lib/openapi/sourcetools/common.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright © 2021-2025 Ismo Kärkkäinen
+# Copyright © 2021-2026 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
 require 'pathname'
@@ -56,6 +56,19 @@ module OpenAPISourceTools
       parts
     end
 
+    # Occasionally saved YAML has aliases. This is added to avoid them.
+    def self.ensure_separate(obj)
+      if obj.is_a?(Array)
+        return obj.map { |v| ensure_separate(v) }
+      end
+      return obj unless obj.is_a?(Hash)
+      out = {}
+      obj.each do |key, value|
+        out[key] = ensure_separate(value)
+      end
+      out
+    end
+
     def self.load_source(input)
       YAML.safe_load(input.nil? ? $stdin : File.read(input))
     rescue Errno::ENOENT
@@ -65,7 +78,9 @@ module OpenAPISourceTools
     end
 
     def self.dump_result(output, doc, error_return)
-      doc = YAML.dump(doc, line_width: 1_000_000) unless doc.is_a?(String)
+      # Safe load did not allow aliases, but saved output may have them.
+      # Observed with empty object or array.
+      doc = YAML.dump(ensure_separate(doc), line_width: 1_000_000) unless doc.is_a?(String)
       if output.nil?
         $stdout.puts doc
       else

data/lib/openapi/sourcetools/generate.rb

@@ -4,6 +4,7 @@
 # Copyright © 2024-2025 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
+require 'fileutils'
 require_relative 'common'
 require_relative 'loaders'
 require_relative 'gen'

data/lib/openapi/sourcetools/output.rb

@@ -1,21 +1,30 @@
 # frozen_string_literal: true
 
-# Copyright © 2024-2025 Ismo Kärkkäinen
+# Copyright © 2024-2026 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
+require 'json'
+require 'yaml'
+
 
 module OpenAPISourceTools
   # Output configuration settings for easy storage.
   # You can have it in configuration and pass hash to initialize.
   class OutputConfiguration
     attr_reader :indent_character, :indent_step
-    attr_reader :tab, :tab_replaces_count
+    attr_reader :tab, :tab_replaces_count, :prettified_json
 
     def initialize(cfg = {})
       @indent_character = cfg['indent_character'] || ' '
       @indent_step = cfg['indent_step'] || 4
       @tab = cfg['tab'] || "\t"
       @tab_replaces_count = cfg['tab_replaces_count'] || 0
+      @prettified_json = {
+        array_nl: "\n",
+        object_nl: "\n",
+        indent: '  ',
+        space: ' '
+      }.merge(cfg['prettified_json'] || {})
     end
   end
 
@@ -81,5 +90,17 @@ module OpenAPISourceTools
       @last_indent = indent
       indented.join(separator)
     end
+
+    def yaml(something)
+      YAML.dump(something)
+    end
+
+    def json(something)
+      JSON.generate(something)
+    end
+
+    def pretty_json(something)
+      JSON.generate(something, @config.prettified_json)
+    end
   end
 end

data/lib/openapi/sourcetools/version.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-# Copyright © 2025 Ismo Kärkkäinen
+# Copyright © 2025-2026 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
 module OpenAPISourceTools
   NAME = 'openapi-sourcetools'
-  VERSION = '0.9.2'
+  VERSION = '0.11.0'
 
   def self.info(separator = ': ')
     "#{NAME}#{separator}#{VERSION}"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: openapi-sourcetools
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.11.0
 platform: ruby
 authors:
 - Ismo Kärkkäinen
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: deep_merge
@@ -43,6 +42,7 @@ executables:
 - openapi-addschemas
 - openapi-addsecurityschemes
 - openapi-checkschemas
+- openapi-clearrefs
 - openapi-frequencies
 - openapi-generate
 - openapi-merge
@@ -59,6 +59,7 @@ files:
 - bin/openapi-addschemas
 - bin/openapi-addsecurityschemes
 - bin/openapi-checkschemas
+- bin/openapi-clearrefs
 - bin/openapi-frequencies
 - bin/openapi-generate
 - bin/openapi-merge
@@ -82,7 +83,6 @@ licenses:
 - UPL-1.0
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -97,8 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Tools for creating source code from API specification.
 test_files: []