openapi-sourcetools 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a91c5ab72a092af55c0caae79470cc3e7d4b7567547f48be039e0c7c3b957d3e
+  data.tar.gz: 02aa4b9a9dd541b2fbce410fb71ecacee7cea40621327dee907c08253688d830
+SHA512:
+  metadata.gz: b44257770c3112bd7441f7ef70e6e4ff4930a55d99501fb58c77e5f5114489b03bb8c1c092ab44445c73719d3afc5fdd6d7bf389f0d28d0b38d06a631a88a521
+  data.tar.gz: fd596ef20c71daa9d9af1f8b44842369ae11e6910d2a96c9b7e0d795e5f351a4fab1d446233e1b6731b5af13edb9a88ab6702842412c1e1071c92d02a6e84d20

data/LICENSE.txt

@@ -0,0 +1,17 @@
+Copyright (c) 2019 Ismo Kärkkäinen
+
+The Universal Permissive License (UPL), Version 1.0
+
+Subject to the condition set forth below, permission is hereby granted to any person obtaining a copy of this software, associated documentation and/or data (collectively the "Software"), free of charge and under any and all copyright rights in the Software, and any and all patent rights owned or freely licensable by each licensor hereunder covering either (i) the unmodified Software as contributed to or provided by such licensor, or (ii) the Larger Works (as defined below), to deal in both
+
+(a) the Software, and
+
+(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if one is included with the Software (each a “Larger Work” to which the Software is contributed by such licensors),
+
+without restriction, including without limitation the rights to copy, create derivative works of, display, perform, and distribute the Software and make, use, sell, offer for sale, import, export, have made, and have sold the Software and the Larger Work(s), and to sublicense the foregoing rights on either these or other terms.
+
+This license is subject to the following condition:
+
+The above copyright notice and either this complete permission notice or at a minimum a reference to the UPL must be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/bin/openapi-frequencies

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2021 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require '../lib/common.rb'
+require 'optparse'
+require 'yaml'
+require 'json'
+
+
+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}
+
+Matches given file with paths and adds frequency information.
+)
+    exit 0
+  end
+end
+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?
+
+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))
+
+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
+      end
+      break
+    end
+  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
+end
+
+case env(:format)
+when 'JSON' then output.puts JSON.generate(doc)
+when 'YAML' then output.puts YAML.dump(doc)
+end
+output.close

data/bin/openapi-generatecode

@@ -0,0 +1,128 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2021 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require '../lib/common.rb'
+require 'optparse'
+require 'yaml'
+require 'erb'
+
+
+default_env(:out, '')
+default_env(:in, '')
+default_env(:template, '')
+
+ENV['POSIXLY_CORRECT'] = '1'
+parser = OptionParser.new do |opts|
+  opts.summary_indent = '  '
+  opts.summary_width = 26
+  opts.banner = 'Usage: openapi-generatecode [options] [additions...]'
+  opts.separator ''
+  opts.separator 'Options (equivalent environment variable and value in parentheses):'
+  opts.on('-i', '--input FILE', 'Read processed API 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('-t', '--template FILE', 'Read template from FILE (TEMPLATE=FILE).') do |f|
+    env(:template, f)
+  end
+  opts.on('-h', '--help', 'Print this help and exit.') do
+    $stdout.puts %(#{opts}
+
+Loads ERB template and optional additions to a context along with the processed
+API document and produces the template result.
+)
+    exit 0
+  end
+end
+parser.parse!
+
+aargh('Template file name must be given.', 1) if env(:template).empty?
+
+def load_content(name)
+  name.empty? ? $stdin.read : File.read(name)
+rescue Errno::ENOENT
+  aargh("Could not load #{name || 'stdin'}", 2)
+rescue StandardError => e
+  aargh("#{e}\nFailed to read #{name || 'stdin'}", 2)
+end
+
+class Generator
+  attr_accessor :addition, :order, :full_name_order, :template, :document
+
+  def initialize(document_content, template_content)
+    @addition = Hash.new
+    @order = []
+    @full_name_order = []
+    @document = document_content
+    @template = template_content
+  end
+
+  def get_binding
+    binding
+  end
+
+  def add(name, content, strip_suffix)
+    @full_name_order.push({ filename: name, contents: content })
+    name = File.basename(name)
+    @order.push name
+    if strip_suffix
+      idx = name.rindex('.')
+      name = name.slice(0, idx) unless idx.nil?
+    end
+    @addition[name] = content
+  end
+end
+t = load_content(env(:template))
+d = load_content(env(:in))
+begin
+  $generator = Generator.new(YAML.safe_load(d), t)
+rescue StandardError => e
+  aargh('Failed to parse API document.', 3)
+end
+
+ARGV.each do |name|
+  aargh('Addition file name is empty.', 1) if name.empty?
+  if name.end_with? '.rb'
+    begin
+      require File.absolute_path(name)
+    rescue SyntaxError => e
+      aargh("Syntax error in addition #{name}: #{e.to_s}", 4)
+    rescue StandardError => e
+      aargh("Failed to require addition #{name}: #{e.to_s}", 5)
+    end
+  else
+    c = load_content(name)
+    begin
+      d = YAML.safe_load(c)
+    rescue StandardError
+      d = c
+    end
+    $generator.add(name, d, name.upcase.end_with?('.YAML') || name.upcase.end_with?('.JSON'))
+  end
+end
+
+begin
+  out = ERB.new($generator.template).result($generator.get_binding)
+rescue SyntaxError => e
+  aargh("Template syntax error: #{e.to_s}", 6)
+rescue StandardError => e
+  aargh("Template error: #{e.to_s}", 7)
+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}", 1)
+  end
+end
+output.write(out)
+output.close

data/bin/openapi-merge

@@ -0,0 +1,171 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2021 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require '../lib/common.rb'
+require 'optparse'
+require 'yaml'
+require 'json'
+require 'set'
+
+
+default_env(:out, '')
+default_env(:format, 'YAML')
+default_env(:prune, false);
+
+ENV['POSIXLY_CORRECT'] = '1'
+parser = OptionParser.new do |opts|
+  opts.summary_indent = '  '
+  opts.summary_width = 26
+  opts.banner = 'Usage: openapi-merge [options] sources...'
+  opts.separator ''
+  opts.separator 'Options (equivalent environment variable and value in parentheses):'
+  opts.on('-o', '--output FILE', 'Output result to FILE, not stdout (OUT=FILE).') do |f|
+    env(:out, f)
+  end
+  opts.on('-p', '--prune', 'Remove all unreferenced objects under components.') do
+    env(:prune, true)
+  end
+  opts.on('--yaml', 'Output format is YAML (default).') do
+    env(:format, 'YAML')
+  end
+  opts.on('--json', 'Output format is JSON.') do
+    env(:format, 'JSON')
+  end
+  opts.on('-h', '--help', 'Print this help and exit.') do
+    $stdout.puts %(#{opts}
+
+Source files are combined to form one API specification document. Sources are
+allowed only to append to the merged document, not re-define anything in it.
+)
+    exit 0
+  end
+end
+parser.parse!
+
+aargh("Format neither JSON nor YAML: #{env(:format)}", 1) unless %w[JSON YAML].include? env(:format)
+
+def read_source(filename)
+  YAML.safe_load(File.read(filename))
+rescue Errno::ENOENT => e
+  aargh("Could not read #{filename}", 2)
+rescue StandardError => e
+  aargh(e.to_s, 3)
+end
+
+def raise_se(message)
+  raise StandardError, message
+end
+
+def path_combo(path, prefix = true)
+  if prefix
+    path.empty? ? 'at root' : "under #{path.join('.')}"
+  else
+    path.empty? ? 'root' : path.join('.')
+  end
+end
+
+def too_deep(path, max_depths)
+  return false if path.empty?
+  max_depths.fetch(path.first) <= path.size
+end
+
+def add_undefined(merged, incoming, filename, path, max_depths)
+  incoming.each_pair do |key, value|
+    unless merged.has_key? key
+      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.class == 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)
+      path.pop
+    elsif m.is_a? Array
+      value.each do |v|
+        next if m.include? v
+        m.push v
+      end
+    else
+      raise_se "Re-definition of #{key} #{path_combo(path)} in #{filename}"
+    end
+  end
+rescue StandardError => e
+  aargh(e.to_s, 3)
+end
+
+max_depths = Hash.new(0)
+max_depths['openapi'] = 1
+max_depths['info'] = 1
+max_depths['servers'] = 1
+max_depths['paths'] = 2 # Allows get, post, options, etc. from different files.
+max_depths['webhooks'] = 2
+max_depths['components'] = 2
+max_depths['security'] = 1
+max_depths['tags'] = 1
+merged = {}
+ARGV.each do |filename|
+  add_undefined(merged, read_source(filename), filename, [], max_depths)
+end
+
+def gather_refs(doc, found)
+  doc.each_pair do |key, value|
+    if key == '$ref' && value.is_a?(String) && value.start_with?('#/components/')
+      found.add(value)
+    elsif value.is_a? Hash
+      gather_refs(value, found)
+    elsif value.is_a? Array
+      value.each do |v|
+        gather_refs(v, found) if v.is_a? Hash
+      end
+    end
+  end
+end
+
+if env(:prune)
+  refs = Set.new
+  gather_refs(merged, refs)
+  used = {}
+  all = merged.fetch('components', {})
+  refs.each do |ref|
+    p = ref.split('/')
+    p.shift(2)
+    item = all
+    p.each do |key|
+      item = item.fetch(key, nil)
+      break if item.nil?
+    end
+    next if item.nil?
+    sub = used
+    p.each_index do |k|
+      if k + 1 < p.size
+        sub[p[k]] = {} unless sub.has_key? p[k]
+        sub = sub[p[k]]
+      else
+        sub[p[k]] = item
+      end
+    end
+  end
+  merged['components'] = used
+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}", 1)
+  end
+end
+
+case env(:format)
+when 'JSON' then output.puts JSON.generate(merged)
+when 'YAML' then output.puts YAML.dump(merged)
+end
+output.close

data/bin/openapi-processpaths

@@ -0,0 +1,111 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2021 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require '../lib/common.rb'
+require 'optparse'
+require 'yaml'
+require 'json'
+
+
+default_env(:in, '')
+default_env(:out, '')
+default_env(:format, 'YAML')
+default_env(:error, true)
+
+parser = OptionParser.new do |opts|
+  opts.summary_indent = '  '
+  opts.summary_width = 24
+  opts.banner = 'Usage: openapi-processpaths [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('--warn', 'Only warn of paths with same fixed parts (ERROR=0).') do
+    env(:error, false)
+  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}
+
+Processes API specification document path objects into form that is expected by
+later stage tools. Checks for paths that may be ambiguous.
+)
+    exit 0
+  end
+end
+parser.parse!
+
+aargh("Format neither JSON nor YAML: #{env(:format)}", 1) unless %w[JSON YAML].include? env(:format)
+
+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))
+
+processed = {}
+doc.fetch('paths', {}).each_pair do |path, value|
+  parts = split_path(path, true)
+  processed[path] = {
+    'parts' => parts,
+    'orig' => value,
+    'lookalike' => [],
+    path: ServerPath.new(parts)
+  }
+end
+
+# Find lookalike sets.
+lookalikes = false
+paths = processed.keys.sort
+paths.each_index do |k|
+  pk = paths[k]
+  a = processed[pk]
+  (0...k).each do |n|
+    pn = paths[n]
+    b = processed[pn]
+    next unless (a[:path].compare(b[:path])) == 0
+    a['lookalike'].push pn
+    b['lookalike'].push pk
+    $stderr.puts("Similar: #{pn} #{pk}")
+    lookalikes = true
+  end
+end
+aargh('Similar paths found.', 7) if lookalikes && env(:error)
+
+# Clean-up temporary fields.
+processed.each_value do |v|
+  v.keys.each { |k| v.delete(k) if k.is_a? Symbol }
+end
+doc['paths'] = processed
+
+output = env(:out)
+if output.empty?
+  output = $stdout
+else
+  begin
+    output = File.open(output, 'w')
+  rescue StandardError
+    aargh("Failed to open for writing: #{output}", 6)
+  end
+end
+
+case env(:format)
+when 'JSON' then output.puts JSON.generate(doc)
+when 'YAML' then output.puts YAML.dump(doc)
+end
+output.close

data/lib/common.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+def aargh(message, exit_code = nil)
+  $stderr.puts message
+  exit exit_code unless exit_code.nil?
+end
+
+def env(var, value = nil)
+  k = var.to_s.upcase
+  ENV[k] = { false => '0', true => '1' }.fetch(value, value) unless value.nil?
+  v = ENV.fetch(k, nil)
+  case v
+  when '0' then false
+  when '1' then true
+  else
+    v
+  end
+end
+
+def default_env(var, value)
+  v = env(var)
+  env(var, value) if v.nil?
+end
+
+def split_path(p, spec = false)
+  parts = []
+  p = p.strip
+  unless spec
+    q = p.index('?')
+    p.slice!(0...q) unless q.nil?
+  end
+  p.split('/').each do |s|
+    next if s.empty?
+    s = { var: s } if spec && s.include?('{')
+    parts.push(s)
+  end
+  parts
+end
+
+ServerPath = Struct.new(:parts) do
+  def <=>(p) # Variables are after fixed strings.
+    pp = p.is_a?(Array) ? p : p.parts
+    parts.each_index do |k|
+      return 1 if pp.size <= k # Longer comes after shorter.
+      pk = parts[k]
+      ppk = pp[k]
+      if pk.is_a? String
+        if ppk.is_a? String
+          c = pk <=> ppk
+        else
+          return -1
+        end
+      else
+        if ppk.is_a? String
+          return 1
+        else
+          c = pk.fetch('var', '') <=> ppk.fetch('var', '')
+        end
+      end
+      return c unless c.zero?
+    end
+    (parts.size < pp.size) ? -1 : 0
+  end
+
+  def compare(p, range = nil) # Not fit for sorting. Variable equals anything.
+    pp = p.is_a?(Array) ? p : p.parts
+    if range.nil?
+      range = 0...parts.size
+    elsif range.is_a? Number
+      range = range...(range + 1)
+    end
+    range.each do |k|
+      return 1 if pp.size <= k # Longer comes after shorter.
+      ppk = pp[k]
+      next unless ppk.is_a? String
+      pk = parts[k]
+      next unless pk.is_a? String
+      c = pk <=> ppk
+      return c unless c.zero?
+    end
+    (parts.size < pp.size) ? -1 : 0
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: openapi-sourcetools
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- Ismo Kärkkäinen
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-10-05 00:00:00.000000000 Z
+dependencies: []
+description: |2
+
+  Tools for generating source code from API specification in OpenAPI format.
+email: ismokarkkainen@icloud.com
+executables:
+- openapi-generatecode
+- openapi-frequencies
+- openapi-merge
+- openapi-processpaths
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- bin/openapi-frequencies
+- bin/openapi-generatecode
+- bin/openapi-merge
+- bin/openapi-processpaths
+- lib/common.rb
+homepage: https://xn--ismo-krkkinen-gfbd.fi/openapi-sourcetools/index.html
+licenses:
+- UPL-1.0
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key:
+specification_version: 4
+summary: Tools for creating source code from API specification.
+test_files: []