openapi-sourcetools 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 205e65ab29d8392a612d241cf0afc0197aba2884c076a7cbeb6523399520e573
-  data.tar.gz: f3cc5e36a89cc174c260a695c5e7d21914660ad8c3813e15d78b03409a964373
+  metadata.gz: 23e0cd1aefa69559d35171e477d8b749ec61251b67c51040b1130ce48fb57725
+  data.tar.gz: 1fa4a40b88aa863d3eed153db455aed0bd4d9b9b88a4aa9ca8f92874e07613f5
 SHA512:
-  metadata.gz: ec20a103c6150baccb9d8ff315bdf3849993fd977ef4738c251f77aefc07b9dbc4f6521e55b14445d07df04dde2cf307bd0d025a33d124b272fea0052f69a956
-  data.tar.gz: 6c763b05cf087a982a53106ca9f889c221cea2788c57fddb1e120b1287f15a8a7d4e42711e0c24c1b87f79187b38f27cf431de918502609317d35deedfe0d170
+  metadata.gz: c56924c74979a016aeb8789bd7071f0d54e3c1de746c7bd92d9166cf0a03001f76f5b7b772d128f3e278bbc7835f52f7f139e4c71fe814032c49a252c24f6ece
+  data.tar.gz: f7c87b497a0c154d99b7cbd33da06cce91e9a7aa8d6b8d72bc6b64f86a50fa1f93a93a0e96f922dab1fdb0c189989cd197f48d12ee5399254fe78120e286ddd4

data/LICENSE.txt

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

data/bin/openapi-addheaders

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2024 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative '../lib/apiobjects'
+require_relative '../lib/common'
+require 'optparse'
+require 'yaml'
+
+
+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 = Components.new(path, 'Header')
+
+  ENV['POSIXLY_CORRECT'] = '1'
+  parser = OptionParser.new do |opts|
+    opts.summary_indent = '  '
+    opts.summary_width = 26
+    opts.banner = 'Usage: openapi-addheaders [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
+    components.add_options(opts)
+    opts.on('-h', '--help', 'Print this help and exit.') do
+      $stdout.puts %(#{opts}
+
+Loads API document in OpenAPI format and moves headers under components and
+replaces the original with reference.
+
+#{components.help}
+)
+      exit 0
+    end
+  end
+  parser.parse!
+
+  doc = 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)
+  bury(doc, path, components.items) unless components.items.empty?
+
+  dump_result(output_name, YAML.dump(doc, line_width: 1_000_000), 3)
+end
+
+exit(main) if (defined? $unit_test).nil?

data/bin/openapi-addresponses

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2024 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative '../lib/apiobjects'
+require_relative '../lib/common'
+require 'optparse'
+require 'yaml'
+
+
+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 = Components.new(path, 'Response')
+
+  ENV['POSIXLY_CORRECT'] = '1'
+  parser = OptionParser.new do |opts|
+    opts.summary_indent = '  '
+    opts.summary_width = 26
+    opts.banner = 'Usage: openapi-addresponses [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
+    components.add_options(opts)
+    opts.on('-h', '--help', 'Print this help and exit.') do
+      $stdout.puts %(#{opts}
+
+Loads API document in OpenAPI format and moves responses under components and
+replaces the original with reference.
+
+#{components.help}
+)
+      exit 0
+    end
+  end
+  parser.parse!
+
+  doc = load_source(input_name)
+  return 2 if doc.nil?
+
+  components.items = doc.dig(*path) || {}
+  replace_responses(doc.fetch('paths', {}), components)
+  bury(doc, path, components.items) unless components.items.empty?
+
+  dump_result(output_name, YAML.dump(doc, line_width: 1_000_000), 3)
+end
+
+exit(main) if (defined? $unit_test).nil?

data/bin/openapi-addschemas

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2024 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative '../lib/apiobjects'
+require_relative '../lib/common'
+require 'optparse'
+require 'yaml'
+
+
+def remove_subitem(obj, path)
+  return obj.delete(path.first) || {} if path.size == 1
+  parent = obj.dig(*path.take(path.size - 1))
+  return {} if parent.nil?
+  parent.delete(path.last) || {}
+end
+
+def replace_inlines(obj, components, top_level = false)
+  if obj.is_a?(Array)
+    obj.each do |o|
+      return false unless replace_inlines(o, components)
+    end
+    return true
+  end
+  return true unless obj.is_a?(Hash)
+  return true if obj.key?('$ref')
+  # Prior return would be the place to get rid of other keys if so desired.
+  # Is inlined, process parts recursively.
+  items = obj['allOf']
+  items = obj['anyOf'] if items.nil?
+  items = obj['oneOf'] if items.nil?
+  # All above need special treatment in code generation templates.
+  return replace_inlines(items, components) unless items.nil?
+  t = obj['type']
+  if t.nil? # Some kind of intermediate-level object.
+    (obj.keys.sort! { |a, b| a.to_s <=> b.to_s }).each do |key|
+      return false unless replace_inlines(obj[key], components)
+    end
+    return true
+  end
+  case t
+  when 'array'
+    return false unless replace_inlines(obj['items'], components)
+  when 'object'
+    props = obj.fetch('properties', {})
+    props.keys.sort!.each do |name|
+      return false unless replace_inlines(props[name], components)
+    end
+  end
+  obj.replace({ '$ref' => components.reference(obj) }) unless top_level
+  true
+end
+
+def main
+  input_name = nil
+  output_name = nil
+  path = %w[components schemas]
+  components = Components.new(path, 'Schema')
+
+  ENV['POSIXLY_CORRECT'] = '1'
+  parser = OptionParser.new do |opts|
+    opts.summary_indent = '  '
+    opts.summary_width = 26
+    opts.banner = 'Usage: openapi-addschemas [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
+    components.add_options(opts)
+    opts.on('-h', '--help', 'Print this help and exit.') do
+      $stdout.puts %(#{opts}
+
+Loads API document in OpenAPI format and adds a schema for each inline type.
+
+#{components.help}
+)
+      exit 0
+    end
+  end
+  parser.parse!
+
+  doc = load_source(input_name)
+  return 2 if doc.nil?
+
+  # Find schema object and remove it temporarily to prevent being
+  # processed again.
+  components.items = remove_subitem(doc, path)
+  # Get rid of inlined types within existing schemas first.
+  components.items.keys.sort!.each do |k|
+    return 4 unless replace_inlines(components.items[k], components, true)
+  end
+  return 4 unless replace_inlines(doc, components)
+  bury(doc, path, components.items) unless components.items.empty?
+
+  dump_result(output_name, YAML.dump(doc, line_width: 1_000_000), 3)
+end
+
+exit(main) if (defined? $unit_test).nil?

data/bin/openapi-checkschemas

@@ -0,0 +1,217 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2024 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative '../lib/apiobjects'
+require_relative '../lib/common'
+require 'optparse'
+require 'yaml'
+
+
+def typesame(a, b, ignored_keys)
+  return same(a, b, ignored_keys) unless a['type'] == 'object'
+  return same(a, b, ignored_keys) unless b['type'] == 'object'
+  # For each property in a, find out unused mathing property in b that is
+  # also either required or not.
+  # Requiring property affects e.g. C++ by allowing direct membership or
+  # when optional, a pointer that can have nullptr value. Or class instance
+  # or null in TypeScript so I consider required to affect type.
+  pa = a.fetch('properties', {})
+  ra = a.fetch('required', [])
+  pb = b.fetch('properties', {}).merge
+  rb = b.fetch('required', [])
+  pa.each do |aname, aspec|
+    bnames = pb.keys.sort!
+    if ra.include?(aname)
+      bnames.select! { |n| rb.include?(n) }
+    else
+      bnames.reject! { |n| rb.include?(n) }
+    end
+    matched = false
+    bnames.each do |bname|
+      bspec = pb[bname]
+      # Intended use is after openapi-addschemas so same should work as well.
+      if typesame(aspec, bspec, ignored_keys)
+        pb.delete(bname)
+        matched = true
+        break
+      end
+    end
+    return false unless matched
+  end
+  pb.empty? # All matched and nothing left in pb.
+end
+
+def keys2array(keys)
+  keys.to_h { |k| [ k, [] ] }
+end
+
+def gather_equivalencies(components)
+  order = components.items.keys.sort!
+  result = keys2array(order)
+  (order.size - 1).times do |k|
+    item = components.items[order[k]]
+    ((k + 1)...order.size).each do |n|
+      if same(item, components.items[order[n]], components.ignored_keys)
+        result[order[k]].push(order[n])
+        result[order[n]].push(order[k])
+      end
+    end
+  end
+  result.delete_if { |_k, v| v.empty? }
+end
+
+def gather_typematches(components)
+  order = components.items.keys.sort!
+  result = keys2array(order)
+  (order.size - 1).times do |k|
+    item = components.items[order[k]]
+    ((k + 1)...order.size).each do |n|
+      if typesame(item, components.items[order[n]], components.ignored_keys)
+        result[order[k]].push(order[n])
+        result[order[n]].push(order[k])
+      end
+    end
+  end
+  result.delete_if { |_k, v| v.empty? }
+end
+
+def gather_refs(obj, prefix, past, refs)
+  if obj.is_a?(Hash)
+    obj.each do |k, v|
+      if v.is_a?(String) && v.start_with?(prefix)
+        p = past.join('/')
+        if refs.key?(v)
+          refs[v].push(p)
+        else
+          refs[v] = [ p ]
+        end
+      else
+        past.push(k)
+        gather_refs(v, prefix, past, refs)
+        past.pop
+      end
+    end
+  elsif obj.is_a?(Array)
+    obj.size.times do |n|
+      past.push(n)
+      gather_refs(obj[n], prefix, past, refs)
+      past.pop
+    end
+  end
+end
+
+def gather_references(doc, prefix)
+  refs = {}
+  gather_refs(doc, prefix, [], refs)
+  out = {}
+  refs.keys.sort!.each do |k|
+    r = refs[k]
+    next if r.empty?
+    out[k] = r.sort!
+  end
+  out
+end
+
+def drop_untouched(refs, report, prefix)
+  touched = Set.new
+  %w[equivalent typematch].each do |s|
+    r = report[s]
+    next if r.nil?
+    r.keys.each { |k| touched.add("#{prefix}#{k}") }
+  end
+  refs.delete_if { |k, _v| !touched.member?(k) }
+end
+
+def count_refs(refs)
+  counts = {}
+  refs.each { |k, v| counts[k] = v.size }
+  counts
+end
+
+def main
+  input_name = nil
+  output_name = nil
+  path = %w[components schemas]
+  components = Components.new(path, '')
+  equivalent = true
+  typematch = false
+  references = false
+  count = true
+  keep = false
+
+  ENV['POSIXLY_CORRECT'] = '1'
+  parser = OptionParser.new do |opts|
+    opts.summary_indent = '  '
+    opts.summary_width = 26
+    opts.banner = 'Usage: openapi-checkschemas [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('-e', '--[no-]equivalent', "Report equivalent schemas, default #{equivalent}") do |b|
+      equivalent = b
+    end
+    opts.on('-t', '--[no-]typematch', "Report typematch schemas, default #{typematch}") do |b|
+      typematch = b
+    end
+    opts.on('-r', '--[no-]reference', "Report schema references, default #{references}") do |b|
+      references = b
+    end
+    opts.on('-c', '--[no-]count', "Report schema reference counts, default #{count}") do |b|
+      count = b
+    end
+    opts.on('-k', '--[no-]keep', "Keep all schema references/counts, default #{keep}") do |b|
+      keep = b
+    end
+    components.add_options(opts)
+    opts.on('-h', '--help', 'Print this help and exit.') do
+      $stdout.puts %(#{opts}
+
+Loads API document in OpenAPI format and checks if any schemas are duplicates
+of another and to what degree. Equivalency may be an exact match, or property
+names differ but types match.
+
+#{components.help}
+
+Search is performed only at top schema level. References to equivalent types
+are not considered equivalent when references themselves are not equivalent.
+Any allOf, anyOf, oneOf checks merely check the refernces. Hence two different
+allOf schemas may in practice result in equivalent types and that is not
+detected.
+
+Implicit expectation is the openapi-addschemas has been used to process the
+input, as inlined types in requests for example are ignored.
+)
+      exit 0
+    end
+  end
+  parser.parse!
+
+  doc = load_source(input_name)
+  return 2 if doc.nil?
+
+  components.items = doc.dig(*path) || {}
+  report = {}
+  report['equivalent'] = gather_equivalencies(components) if equivalent
+  report['typematch'] = gather_typematches(components) if typematch
+  if references || count
+    refs = gather_references(doc, components.path)
+    if equivalent || typematch # There is something to limit references to.
+      refs = drop_untouched(refs, report, components.path) unless keep
+    end
+    report['reference'] = refs if references
+    report['count'] = count_refs(refs) if count
+  end
+  # Filter reference counts that are not for type in equivalent or typematch.
+  # Could check for pretty-printed output format here.
+  dump_result(output_name, YAML.dump(report, line_width: 80), 3)
+end
+
+exit(main) if (defined? $unit_test).nil?

data/bin/openapi-frequencies

@@ -1,105 +1,78 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Copyright © 2021 Ismo Kärkkäinen
+# Copyright © 2021-2024 Ismo Kärkkäinen
 # Licensed under Universal Permissive License. See LICENSE.txt.
 
-require_relative '../lib/common.rb'
+require_relative '../lib/common'
 require 'optparse'
 require 'yaml'
-require 'json'
 
+def main
+  input_name = nil
+  output_name = nil
+  paths_name = nil
 
-default_env(:in, '')
-default_env(:out, '')
-default_env(:format, 'YAML')
-default_env(:paths, '')
-
-parser = OptionParser.new do |opts|
-  opts.summary_indent = '  '
-  opts.summary_width = 24
-  opts.banner = 'Usage: openapi-frequencies [options]'
-  opts.separator ''
-  opts.separator 'Options (equivalent environment variable and value in parentheses):'
-  opts.on('-i', '--input FILE', 'Read source from FILE, not stdin (IN=FILE).') do |f|
-    env(:in, f)
-  end
-  opts.on('-o', '--output FILE', 'Output result to FILE, not stdout (OUT=FILE).') do |f|
-    env(:out, f)
-  end
-  opts.on('-p', '--paths FILE', 'Path log file name (PATHS=FILE).') do |f|
-    env(:paths, f)
-  end
-  opts.on('--yaml', 'Output format is YAML (default) (FORMAT=YAML).') do
-    env(:format, 'YAML')
-  end
-  opts.on('--json', 'Output format is JSON. (FORMAT=JSON)') do
-    env(:format, 'JSON')
-  end
-  opts.on('-h', '--help', 'Print this help and exit.') do
-    $stdout.puts %(#{opts}
+  parser = OptionParser.new do |opts|
+    opts.summary_indent = '  '
+    opts.summary_width = 24
+    opts.banner = 'Usage: openapi-frequencies [options]'
+    opts.separator ''
+    opts.separator 'Options:'
+    opts.on('-i', '--input FILE', 'Read source from FILE, not stdin.') do |f|
+      input_name = f
+    end
+    opts.on('-o', '--output FILE', 'Output result to FILE, not stdout.') do |f|
+      output_name = f
+    end
+    opts.on('-p', '--paths FILE', 'Path log file name.') do |f|
+      paths_name = f
+    end
+    opts.on('-h', '--help', 'Print this help and exit.') do
+      $stdout.puts %(#{opts}
 
-Matches given file with paths and adds frequency information.
+Matches given OpenAPI document file paths with paths from file and adds
+into each path object matching count as "freq".
 )
-    exit 0
+      exit 0
+    end
   end
-end
-parser.parse!
+  parser.parse!
 
-aargh("Format neither JSON nor YAML: #{env(:format)}", 1) unless %w[JSON YAML].include? env(:format)
-fn = env(:paths)
-aargh("Path log file name must be given.") if fn.empty?
+  return aargh('Path log file name must be given.', 1) if paths_name.nil?
 
-def read_source(filename)
-  YAML.safe_load(filename.empty? ? $stdin : File.read(filename))
-rescue Errno::ENOENT => e
-  aargh("Could not read #{filename.empty? ? 'stdin' : filename}", 2)
-rescue StandardError => e
-  aargh(e.to_s, 3)
-end
-doc = read_source(env(:in))
+  doc = load_source(input_name)
+  return 2 if doc.nil?
 
-begin
-  # Expect one path per line with nothing else. Query is allowed and ignored.
-  f = File.new(fn, 'rt')
-  f.each_line do |line|
-    p = ServerPath.new(split_path(line))
-    doc['paths'].each_value do |info|
-      next unless (p <=> info['parts']) == 0
-      info['freq'] = info.fetch('freq', 0) + 1
-      # Lookalikes are the others that can be matched, since path has no
-      # variables so any change in fixed parts (not a lookalike) will be a
-      # mismatch with path.
-      info['lookalike'].each do |path|
-        cand = doc['paths'][path]
-        next unless (p <=> cand['parts']) == 0
-        cand['freq'] = cand.fetch('freq', 0) + 1
+  begin
+    # Expect one path per line with nothing else. Query is allowed and ignored.
+    f = File.new(paths_name, 'rt')
+    f.each_line do |line|
+      p = ServerPath.new(split_path(line))
+      doc['paths'].each_value do |info|
+        next unless (p <=> info['parts']).zero?
+        info['freq'] = info.fetch('freq', 0) + 1
+        # Lookalikes are the others that can be matched, since path has no
+        # variables so any change in fixed parts (not a lookalike) will be a
+        # mismatch with path.
+        info['lookalike'].each do |path|
+          cand = doc['paths'][path]
+          next unless (p <=> cand['parts']).zero?
+          cand['freq'] = cand.fetch('freq', 0) + 1
+        end
+        break
       end
-      break
     end
+    f.close
+  rescue Errno::ENOENT
+    return aargh("Could not read path log file: #{paths_name}", 4)
+  rescue NoMethodError
+    return aargh('Is input file an output of openapi-processpaths?', 5)
+  rescue StandardError => e
+    return aargh(e.to_s, 6)
   end
-  f.close
-rescue Errno::ENOENT => e
-  aargh("Could not read path log file: #{fn}", 4)
-rescue NoMethodError
-  aargh('Is input file an output of openapi-processpaths?', 5)
-rescue StandardError => e
-  aargh(e.to_s, 6)
-end
 
-output = env(:out)
-if output.empty?
-  output = $stdout
-else
-  begin
-    output = File.open(output, 'w')
-  rescue StandardError
-    aargh("Failed to open for writing: #{output}", 7)
-  end
+  dump_result(output_name, YAML.dump(doc), 3)
 end
 
-case env(:format)
-when 'JSON' then output.puts JSON.generate(doc)
-when 'YAML' then output.puts YAML.dump(doc)
-end
-output.close
+exit(main) if (defined? $unit_test).nil?