openapi-sourcetools 0.10.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b692fd4b41d1d925fc0a51d94faabe7ee1f5ec8ff26c7ee393e37cafd9b9dffe
-  data.tar.gz: 19df615a73ec7f006fffd49f1474fb188dbe0f616c49739f0b28c692f7035ec5
+  metadata.gz: 2b790daa9dc40626f360f32ba98853c2b5410e5214d0d2ef32334df1858a9262
+  data.tar.gz: 842e1b54d72995112b38f678f3b0f853d9e0e6ea03652d56797715cb215e2c35
 SHA512:
-  metadata.gz: d52cdb9cbdea83bbb3ff510c0b73f61d47eb13049b74e452f90eb597d5a3f697dd414b8f4ca6dd7215d8ea9ac3fd397864c8589365e2a295aa575f2cb3d18c7e
-  data.tar.gz: 26b623377edc1c7cbf58721d1bc3a6a649d2bd79098c5b30502f7810678a09f27c6f401452f96020f4ddc8ff2a5546fce40c2904b63ad968421e7563730182ee
+  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

@@ -8,30 +8,14 @@ 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 File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-addparameters

@@ -7,12 +7,12 @@
 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 = '  '
@@ -97,17 +97,17 @@ feature is intended to simplify code generation.
   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) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-addresponses

@@ -7,30 +7,14 @@
 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 File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/bin/openapi-addschemas

@@ -7,7 +7,6 @@
 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 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/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?

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

@@ -5,7 +5,7 @@
 
 module OpenAPISourceTools
   NAME = 'openapi-sourcetools'
-  VERSION = '0.10.1'
+  VERSION = '0.11.0'
 
   def self.info(separator = ': ')
     "#{NAME}#{separator}#{VERSION}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi-sourcetools
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.11.0
 platform: ruby
 authors:
 - Ismo Kärkkäinen
@@ -42,6 +42,7 @@ executables:
 - openapi-addschemas
 - openapi-addsecurityschemes
 - openapi-checkschemas
+- openapi-clearrefs
 - openapi-frequencies
 - openapi-generate
 - openapi-merge
@@ -58,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