openapi-sourcetools 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23e0cd1aefa69559d35171e477d8b749ec61251b67c51040b1130ce48fb57725
-  data.tar.gz: 1fa4a40b88aa863d3eed153db455aed0bd4d9b9b88a4aa9ca8f92874e07613f5
+  metadata.gz: 9320a1d6d4202c453fb7065f00bc534206b1c780560ae443cd30293f27827595
+  data.tar.gz: af45eabe9a8f392c705398957cf276acb39923655207ffda12ee8d93e1c072a0
 SHA512:
-  metadata.gz: c56924c74979a016aeb8789bd7071f0d54e3c1de746c7bd92d9166cf0a03001f76f5b7b772d128f3e278bbc7835f52f7f139e4c71fe814032c49a252c24f6ece
-  data.tar.gz: f7c87b497a0c154d99b7cbd33da06cce91e9a7aa8d6b8d72bc6b64f86a50fa1f93a93a0e96f922dab1fdb0c189989cd197f48d12ee5399254fe78120e286ddd4
+  metadata.gz: 1f81cae3adb06d42d3bf5361615a0a21ca42346d08b1f8b83462116668d2ad61ec05ac707e723d910bbe55eb29699129ba13570b44504581e92597242ab3d810
+  data.tar.gz: 656959f866321cd68814fed2ef1c9121fe1db36674cb7fbd49f9f2a652e5f43a29d6b1d491a2197278577084d1328e01f99fd1eff8fca1c7ef7d6299ed512b17

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

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2021-2024 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative '../lib/common'
+require_relative '../lib/loaders'
+require_relative '../lib/gen'
+require_relative '../lib/generate'
+require 'optparse'
+require 'yaml'
+
+
+def main
+  input_name = nil
+  output_dir = nil
+
+  ENV['POSIXLY_CORRECT'] = '1'
+  parser = OptionParser.new do |opts|
+    opts.summary_indent = '  '
+    opts.summary_width = 26
+    opts.banner = 'Usage: openapi-generate [options] generator-names...'
+    opts.separator ''
+    opts.separator 'Options:'
+    opts.on('-i', '--input FILE', 'Read processed API from FILE, not stdin.') do |f|
+      input_name = f
+    end
+    opts.on('-o', '--outdir DIR', 'Output directory.') do |d|
+      output_dir = d
+    end
+    opts.on('-h', '--help', 'Print this help and exit.') do
+      $stdout.puts %(#{opts}
+Loads API document in OpenAPI format and generator names. Built-in generator
+loaders accept the following:
+#{Loaders.document.strip}
+
+During load each generator can add and modify tasks via Gen module:
+#{Gen.document.strip}
+
+After all generators have loaded succesfully, tasks are run.
+)
+      exit 0
+    end
+  end
+  parser.parse!
+
+  return aargh('Generator names must be given.', 1) if ARGV.empty?
+
+  a = load_source(input_name)
+  return 2 if a.nil?
+  return aargh("Not a directory: #{output_dir}", 3) unless File.directory?(output_dir)
+  gen = Generator.new(a, input_name, output_dir)
+  ec = gen.load(ARGV)
+  return ec unless ec.zero?
+  gen.run
+end
+
+exit(main) if defined?($unit_test).nil?

data/lib/apiobjects.rb

@@ -85,11 +85,7 @@ class PathOperation
   attr_accessor :summary, :description
 end
 
-# Should mapping JSON schema types to native types be a separate step?
-# Just add x-openapi-sourcetools-native: nativetype
-# Separate program that can pipe modified spec out to code generation?
-
-# JSON schema is way too complex to simplify here. One could have a convenience
+# One could have a convenience
 # method that determines how many bytes the value needs, and if it needs to be
 # signed.
 
@@ -302,3 +298,36 @@ class SchemaOrderer
     chosen
   end
 end
+
+class HeaderOrderer
+end
+
+class ResponseOrderer
+end
+
+class PathOrderer
+end
+
+class Tasker
+  attr_reader :doc
+  def initialize(doc)
+    @doc = doc
+  end
+end
+
+class SchemaTasker < Tasker
+# initialize with doc
+# Orderer set somehow.
+# Method ot create one task per schema.
+# Method to create one task for all schemas.
+end
+
+class HeaderTasker < Tasker
+# initialize with doc
+# Orderer set somehow.
+# Method ot create one task per schema.
+# Method to create one task for all schemas.
+end
+
+
+

data/lib/common.rb

@@ -21,7 +21,7 @@ def bury(doc, path, value)
   doc[path.last] = value
 end
 
-module Output
+module Out
   attr_reader :count
 
   def put(message)

data/lib/gen.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# Copyright © 2024 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'task'
+require_relative 'helper'
+
+
+module Gen
+  def self.mod_attr_reader(symbol, docstr = nil)
+    attr_reader(symbol)
+    module_function(symbol)
+    return if docstr.nil?
+    @docsrc = [] unless Gen.instance_variable_defined?('@docsrc')
+    @docsrc.push("- #{symbol.to_s} : #{docstr}")
+  end
+
+  def self.mod_attr_accessor(symbol, docstr = nil)
+    attr_accessor(symbol)
+    module_function(symbol)
+    s = symbol.to_s
+    module_function((s + '=').to_sym)
+    return if docstr.nil?
+    @docsrc = [] unless Gen.instance_variable_defined?('@docsrc')
+    @docsrc.push("- #{s} : #{docstr}")
+  end
+
+  mod_attr_reader :doc, 'OpenAPI document.'
+  mod_attr_reader :outdir, 'Output directory name.'
+  mod_attr_accessor :in_name, 'OpenAPI document name, nil if stdin.'
+  mod_attr_accessor :in_basename, 'OpenAPI document basename, nil if stdin.'
+  mod_attr_accessor :tasks, 'Tasks array.'
+  mod_attr_accessor :g, 'Hash for storing values visible to all tasks.'
+  mod_attr_accessor :a, 'Intended for instance with defined attributes.'
+  mod_attr_accessor :h, 'Instance of class with helper methods.'
+  mod_attr_accessor :t, 'Current task instance.'
+  mod_attr_accessor :task_index, 'Current task index.'
+  mod_attr_accessor :loaders, 'Array of generator loader methods.'
+
+  def self.setup(document_content, input_name, output_directory)
+    @doc = document_content
+    @outdir = output_directory
+    if input_name.nil?
+      @in_name = nil
+      @in_basename = nil
+    else
+      @in_name = File.basename(input_name)
+      @in_basename = File.basename(input_name, '.*')
+    end
+    @tasks = []
+    @g = {}
+    @a = nil
+    @h = nil
+    @t = nil
+    @task_index = nil
+    @loaders = []
+    add_task(task: HelperTask.new)
+  end
+
+  def self.add_task(task:, name: nil, executable: false, x: nil)
+    @tasks.push(task)
+    # Since this method allows the user to pass their own task type instance,
+    # assign optional values with defaults only when clearly given.
+    @tasks.last.name = name unless name.nil?
+    @tasks.last.executable = executable unless executable == false
+    @tasks.last.x = x unless x.nil?
+  end
+
+  def self.add_write_content(name:, content:, executable: false)
+    add_task(task: WriteTask.new(name, content, executable))
+  end
+
+  def self.add(source:, template: nil, template_name: nil, name: nil, executable: false, x: nil)
+    add_task(task: Task.new(source, template, template_name), name: name, executable: executable, x: x)
+  end
+
+  def self.document
+    @docsrc.join("\n") + %(
+- add_task(task:, name: nil, executable: false, x: nil) : Adds task object.
+- add_write_content(name:, content:, executable: false) : Add file write task.
+- add(source:, template: nil, template_name: nil, name: nil,
+    executable: false, x: nil) :
+  Adds template task with source as object to process.
+)
+  end
+end

data/lib/generate.rb

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2024 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'common'
+require_relative 'loaders'
+require_relative 'gen'
+
+def executable_bits_on(mode)
+  mode = mode.to_s(8).split('')
+  mode.size.times do |k|
+    m = mode[k].to_i(8)
+    # Applies to Unix-likes. Other system, check and handle.
+    m += 1 unless 3 < mode.size - k || m.zero? || m % 2 == 1
+    mode[k] = m
+  end
+  m = 0
+  mode.each do |v|
+    m = 8 * m + v
+  end
+  m
+end
+
+class Generator
+  def initialize(document_content, input_name, output_directory)
+    Gen.setup(document_content, input_name, output_directory)
+    Gen.loaders = Loaders.loaders
+  end
+
+  def context_binding
+    binding
+  end
+
+  def load(generator_names)
+    generator_names.each do |name|
+      idx = Gen.loaders.index { |loader| loader.call(name) }
+      return aargh("No loader could handle #{name}", 2) if idx.nil?
+    end
+    0
+  rescue StandardError => e
+    aargh(e.to_s, 2)
+  end
+
+  def generate(t)
+    t.generate(context_binding)
+  rescue Exception => e
+    aargh(e.to_s, 4)
+  end
+
+  def output_name(t, index)
+    name = t.output_name
+    name = "#{index}.txt" if name.nil?
+    File.join(Gen.outdir, name)
+  end
+
+  def save(name, contents, executable)
+    f = File.new(name, File::WRONLY | File::CREAT | File::TRUNC)
+    s = executable ? f.stat : nil
+    f.write(contents)
+    f.close
+    return unless executable
+    mode = executable_bits_on(s.mode)
+    File.chmod(mode, name) unless mode == s.mode
+  end
+
+  def run
+    # This allows tasks to be added while processing.
+    # Not intended to be done but might prove handy.
+    # Also exposes current task index in case new task is added in the middle.
+    Gen.task_index = 0
+    while Gen.task_index < Gen.tasks.size
+      Gen.t = Gen.tasks[Gen.task_index]
+      out = generate(Gen.t)
+      Gen.task_index += 1
+      next if Gen.t.discard # Check first to ignore result if no output.
+      return out if out.is_a?(Integer)
+      next if out.empty? # Allows no output but return value still checked.
+      name = output_name(Gen.t, Gen.task_index - 1)
+      begin
+        save(name, out, Gen.t.executable)
+      rescue StandardError => e
+        return aargh("Error writing output file: #{name}\n#{e}", 3)
+      end
+    end
+    0
+  end
+end

data/lib/helper.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# Copyright © 2024 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'task'
+
+
+class Helper
+  attr_reader :doc, :parents
+  attr_accessor :parent_parameters
+
+  # Stores the nearesh Hash for each Hash.
+  def store_parents(obj, parent = nil)
+    if obj.is_a?(Hash)
+      @parents[obj.object_id] = parent
+      obj.each do |k, v|
+        store_parents(v, obj)
+      end
+    elsif obj.is_a?(Array)
+      obj.each do |v|
+        store_parents(v, parent)
+      end
+    end
+  end
+
+  def initialize(doc)
+    @doc = doc
+    # For each hash in doc, set parent?
+    # Build an object_id to parent object mapping and use parent method?
+    @parents = {}
+    store_parents(@doc)
+  end
+
+  def parent(object)
+    @parents[object.object_id]
+  end
+
+  COMPONENTS = '#/components/'
+
+  def category_and_name(ref_or_obj)
+    ref = ref_or_obj.is_a?(Hash) ? ref_or_obj['$ref'] : ref_or_obj
+    return nil unless ref.is_a?(String)
+    return nil unless ref.start_with?(Helper::COMPONENTS)
+    idx = ref.index('/', Helper::COMPONENTS.size)
+    return nil if idx.nil?
+    category = ref[Helper::COMPONENTS.size...idx]
+    [ category, ref[(idx + 1)...ref.size] ]
+  end
+
+  def dereference(ref_or_obj)
+    cn = category_and_name(ref_or_obj)
+    return nil if cn.nil?
+    cs = @doc.dig('components', cn.first) || {}
+    cs[cn.last]
+  end
+
+  def basename(ref_or_obj)
+    cn = category_and_name(ref_or_obj)
+    return nil if cn.nil?
+    cn.last
+  end
+
+  def parameters(operation_object, empty_unless_local = false)
+    return [] if empty_unless_local && !operation_object.key?('parameters')
+    cps = @doc.dig('components', 'parameters') || {}
+    uniqs = {}
+    path_item_object = parent(operation_object)
+    [path_item_object, operation_object].each do |p|
+      p.fetch('parameters', []).each do |param|
+        r = basename(param)
+        r = cps[r] if r.is_a?(String)
+        uniqs["#{r['name']}:#{r['in']}"] = param
+      end
+    end
+    uniqs.keys.sort!.map { |k| uniqs[k] }
+  end
+end
+
+
+class HelperTask
+  include TaskInterface
+
+  def generate(context_binding)
+    Gen.h = Helper.new(Gen.doc)
+  end
+
+  def output_name
+    nil
+  end
+
+  def discard
+    true
+  end
+end
+

data/lib/loaders.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Copyright © 2024 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+module Loaders
+
+  GEM_PREFIX = 'gem:'
+
+  def self.gem_loader(name)
+    return false unless name.downcase.start_with?(GEM_PREFIX)
+    begin
+      require(name.slice(GEM_PREFIX.size...name.size))
+    rescue LoadError => e
+      raise StandardError, "Failed to require #{name}\n#{e.to_s}"
+    rescue Exception => e
+      raise StandardError, "Problem with #{name}\n#{e.to_s}"
+    end
+    true
+  end
+
+  RUBY_EXT = '.rb'
+
+  def self.ruby_loader(name)
+    return false unless name.downcase.end_with?(RUBY_EXT)
+    origwd = Dir.pwd
+    d = File.dirname(name)
+    Dir.chdir(d) unless d == '.'
+    begin
+      require(File.join(Dir.pwd, File.basename(name)))
+    rescue LoadError => e
+      raise StandardError, "Failed to require #{name}\n#{e.to_s}"
+    rescue Exception => e
+      raise StandardError, "Problem with #{name}\n#{e.to_s}"
+    end
+    Dir.chdir(origwd) unless d == '.'
+    true
+  end
+
+  def self.loaders
+    [ method(:gem_loader), method(:ruby_loader) ]
+  end
+
+  def self.document
+    %(
+- #{Loaders::GEM_PREFIX}gem_name : requires the gem.
+- ruby_file#{Loaders::RUBY_EXT} : changes to Ruby file directory and requires the file.
+)
+  end
+
+end

data/lib/task.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+# Copyright © 2024 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require 'erb'
+require_relative 'common'
+
+
+module TaskInterface
+  def generate(context_binding)
+    raise NotImplementedError
+  end
+
+  def output_name
+    raise NotImplementedError
+  end
+
+  def discard
+    false
+  end
+
+  def executable
+    false
+  end
+end
+
+class Task
+  include TaskInterface
+
+  attr_reader :src, :template, :template_name
+  attr_accessor :name, :executable, :discard, :x
+
+  def initialize(src, template, template_name)
+    @src = src
+    @template = template
+    @template_name = template_name
+    if @template.nil?
+      raise ArgumentError, "template_name or template must be given" if @template_name.nil?
+      begin
+        @template = File.read(@template_name)
+      rescue Errno::ENOENT
+        raise StandardError, "Could not load #{@template_name}"
+      rescue StandardError => e
+        raise StandardError, "#{e}\nFailed to read #{@template_name}"
+      end
+    end
+    @name = nil
+    @executable = false
+    @discard = false
+    @x = nil
+  end
+
+  # If this is overridden to perform some processing but not to produce output,
+  # set @discard = true and return value will be ignored. No other methods are
+  # called in that case.
+  def internal_generate(context_binding)
+    ERB.new(@template).result(context_binding)
+  end
+
+  # You can override this instead of internal_generate if you do not need the
+  # exception handling.
+  def generate(context_binding)
+    n = @template_name.nil? ? '' : "#{@template_name} "
+    internal_generate(context_binding)
+  rescue SyntaxError => e
+    aargh("Template #{n}syntax error: #{e.full_message}", 5)
+  rescue Exception => e
+    aargh("Template #{n}error: #{e.full_message}", 6)
+  end
+
+  # This is only called when generate produced output that is not discarded.
+  def output_name
+    return @name unless @name.nil?
+    # Using template name may show where name assignment is missing.
+    # Name assignment may also be missing in the task creation stage.
+    return File.basename(@template_name) unless @template_name.nil?
+    nil
+  end
+end
+
+class WriteTask
+  include TaskInterface
+
+  attr_reader :name, :contents, :executable
+
+  def initialize(name, contents, executable = false)
+    raise ArgumentError, "name and contents must be given" if name.nil? || contents.nil?
+    @name = name
+    @contents = contents
+    @executable = executable
+  end
+
+  def generate(context_binding)
+    @contents
+  end
+
+  def output_name
+    @name
+  end
+end

metadata

@@ -1,27 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: openapi-sourcetools
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Ismo Kärkkäinen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-17 00:00:00.000000000 Z
+date: 2024-07-17 00:00:00.000000000 Z
 dependencies: []
 description: |2
 
   Tools for handling API specification in OpenAPI format. Replacement of
   duplicate definitions with references. Other checks. Does not validate
-  the document against specification.
+  the document against OpenAPI format specification.
 email: ismokarkkainen@icloud.com
 executables:
 - openapi-addheaders
+- openapi-addparameters
 - openapi-addresponses
 - openapi-addschemas
 - openapi-checkschemas
 - openapi-frequencies
+- openapi-generate
 - openapi-merge
 - openapi-processpaths
 extensions: []
@@ -29,14 +31,21 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - bin/openapi-addheaders
+- bin/openapi-addparameters
 - bin/openapi-addresponses
 - bin/openapi-addschemas
 - bin/openapi-checkschemas
 - bin/openapi-frequencies
+- bin/openapi-generate
 - bin/openapi-merge
 - bin/openapi-processpaths
 - lib/apiobjects.rb
 - lib/common.rb
+- lib/gen.rb
+- lib/generate.rb
+- lib/helper.rb
+- lib/loaders.rb
+- lib/task.rb
 homepage: https://xn--ismo-krkkinen-gfbd.fi/openapi-sourcetools/index.html
 licenses:
 - UPL-1.0