openapi-sourcetools 0.4.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dab74fc29224544168525f22fafd82566f0ccce13c331ff67d5c30e7b1cd6f6b
-  data.tar.gz: c43c779d03c612704ffa06558d7c1ccf225e64417a189dc0d889155760453fe2
+  metadata.gz: 9320a1d6d4202c453fb7065f00bc534206b1c780560ae443cd30293f27827595
+  data.tar.gz: af45eabe9a8f392c705398957cf276acb39923655207ffda12ee8d93e1c072a0
 SHA512:
-  metadata.gz: af3fa46f714c20698c08b0d94a1edbafab6d256940a52dbda84eb947aac175816518c9b5f4818dae8e2e750d3e5fb78ee603e3bae0b5b336717316f1cf3cc494
-  data.tar.gz: 7f654330b1f7c4fe90f028c69bb113b808682bdbabff8858e48eebb0ed2e8e2ea2af470cf7b6fe175efcb96721792bc380321dc25a48e521b7243207a8bda5b3
+  metadata.gz: 1f81cae3adb06d42d3bf5361615a0a21ca42346d08b1f8b83462116668d2ad61ec05ac707e723d910bbe55eb29699129ba13570b44504581e92597242ab3d810
+  data.tar.gz: 656959f866321cd68814fed2ef1c9121fe1db36674cb7fbd49f9f2a652e5f43a29d6b1d491a2197278577084d1328e01f99fd1eff8fca1c7ef7d6299ed512b17

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-addparameters

@@ -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_parameter(p, components)
+  return p unless p.is_a?(Hash) # Could complain.
+  return p if p.key?('$ref')
+  { '$ref' => components.reference(p) }
+end
+
+def replace_parameters(obj, components)
+  return unless obj.is_a?(Hash)
+  obj.each do |k, v|
+    if k == 'parameters'
+      obj[k] = v.map { |p| replace_parameter(p, components) }
+    else
+      replace_parameters(v, components)
+    end
+  end
+end
+
+def main
+  input_name = nil
+  output_name = nil
+  path = %w[components parameters]
+  components = Components.new(path, 'Parameter')
+
+  ENV['POSIXLY_CORRECT'] = '1'
+  parser = OptionParser.new do |opts|
+    opts.summary_indent = '  '
+    opts.summary_width = 26
+    opts.banner = 'Usage: openapi-addparameters [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 parameters 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_parameters(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?