openapi-sourcetools 0.7.1 → 0.8.0

data/lib/openapi/sourcetools/generate.rb

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'common'
+require_relative 'loaders'
+require_relative 'gen'
+
+
+module OpenAPISourceTools
+  def self.executable_bits_on(mode)
+    mode = mode.to_s(8).chars
+    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.odd?
+      mode[k] = m
+    end
+    m = 0
+    mode.each do |v|
+      m = 8 * m + v
+    end
+    m
+  end
+
+  # Runs all tasks that generate the results.
+  # Used internally by openapi-generate.
+  class Generator
+    def initialize(document_content, input_name, output_directory, config_prefix)
+      Gen.setup(document_content, input_name, output_directory, config_prefix)
+      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 Common.aargh("No loader could handle #{name}", 2) if idx.nil?
+      end
+      0
+    rescue StandardError => e
+      Common.aargh(e.to_s, 2)
+    end
+
+    def generate(t)
+      t.generate(context_binding)
+    rescue Exception => e
+      Common.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)
+      d = File.dirname(name)
+      FileUtils.mkdir_p(d) unless File.directory?(d)
+      f = File.new(name, File::WRONLY | File::CREAT | File::TRUNC)
+      s = executable ? f.stat : nil
+      f.write(contents)
+      f.close
+      return unless executable
+      mode = OpenAPISourceTools.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]
+        Gen.task = Gen.t
+        out = generate(Gen.t)
+        Gen.task_index += 1
+        return out if out.is_a?(Integer)
+        next if Gen.t.discard || out.empty?
+        name = output_name(Gen.t, Gen.task_index - 1)
+        begin
+          save(name, out, Gen.t.executable)
+        rescue StandardError => e
+          return Common.aargh("Error writing output file: #{name}\n#{e}", 3)
+        end
+      end
+      0
+    end
+  end
+end

data/lib/openapi/sourcetools/helper.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'task'
+
+module OpenAPISourceTools
+  # Helper class supposed to contain helpful methods.
+  # Exposed as Gen.h if HelperTask has been run. It is automatically
+  # added as the first task but later tasks can remove it.
+  class Helper
+    attr_reader :doc, :parents
+    attr_accessor :parent_parameters
+
+    # Stores the nearest Hash for each Hash.
+    def store_parents(obj, parent = nil)
+      if obj.is_a?(Hash)
+        @parents[obj] = parent
+        obj.each_value do |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
+      @parents = {}.compare_by_identity
+      store_parents(@doc)
+    end
+
+    def parent(object)
+      @parents[object]
+    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
+
+  # Task class to add an Helper instance to Gen.h, for convenience.
+  class HelperTask
+    include OpenAPISourceTools::TaskInterface
+
+    def generate(_context_binding)
+      Gen.h = Helper.new(Gen.doc) if Gen.h.nil?
+    end
+
+    def discard
+      true
+    end
+  end
+end

data/lib/openapi/sourcetools/loaders.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'task'
+
+
+# Original loader functions. These are accessible via Gen.loaders. New loaders
+# should be added there.
+module OpenAPISourceTools
+  # Loaders used to load gems and files and set config etc.
+  # Exposed as Gen.loaders if you need to modify the array.
+  module Loaders
+    # Prefix etc. and loader pairs for all loaders.
+
+    REQ_PREFIX = 'req:'
+
+    def self.req_loader(name)
+      return false unless name.downcase.start_with?(REQ_PREFIX)
+      begin
+        t = OpenAPISourceTools::RestoreProcessorStorage.new({})
+        Gen.tasks.push(t)
+        base = name.slice(REQ_PREFIX.size...name.size)
+        require(base)
+        Gen.config = nil
+        t.x = Gen.x # In case setup code replaced the object.
+      rescue LoadError => e
+        raise StandardError, "Failed to require #{name}\n#{e}"
+      rescue Exception => e
+        raise StandardError, "Problem with #{name}\n#{e}\n#{e.backtrace.join("\n")}"
+      end
+      true
+    end
+
+    REREQ_PREFIX = 'rereq:'
+
+    def self.rereq_loader(name)
+      return false unless name.downcase.start_with?(REREQ_PREFIX)
+      begin
+        t = OpenAPISourceTools::RestoreProcessorStorage.new({})
+        Gen.tasks.push(t)
+        code = name.slice(REREQ_PREFIX.size...name.size)
+        eval(code)
+        Gen.config = nil
+        t.x = Gen.x # In case setup code replaced the object.
+      rescue LoadError => e
+        raise StandardError, "Failed to require again #{name}\n#{e}"
+      rescue Exception => e
+        raise StandardError, "Problem with #{name}\n#{e}\n#{e.backtrace.join("\n")}"
+      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
+        t = OpenAPISourceTools::RestoreProcessorStorage.new({})
+        Gen.tasks.push(t)
+        base = File.basename(name)
+        Gen.config = base[0..-4] if Gen.config.nil?
+        require(File.join(Dir.pwd, base))
+        Gen.config = nil
+        t.x = Gen.x # In case setup code replaced the object.
+      rescue LoadError => e
+        raise StandardError, "Failed to require #{name}\n#{e}"
+      rescue Exception => e
+        raise StandardError, "Problem with #{name}\n#{e}\n#{e.backtrace.join("\n")}"
+      end
+      Dir.chdir(origwd) unless d == '.'
+      true
+    end
+
+    YAML_PREFIX = 'yaml:'
+    YAML_EXTS = [ '.yaml', '.yml' ].freeze
+
+    def self.yaml_loader(name)
+      d = name.downcase
+      if d.start_with?(YAML_PREFIX)
+        name = name.slice(YAML_PREFIX.size...name.size)
+      elsif (YAML_EXTS.index { |s| d.end_with?(s) }).nil?
+        return false
+      end
+      n, _sep, f = name.partition(':')
+      raise StandardError, 'No name given.' if n.empty?
+      raise StandardError, 'No filename given.' if f.empty?
+      doc = YAML.safe_load_file(f)
+      raise StandardError, "#{name} #{n} exists already." unless Gen.d.add(n, doc)
+      true
+    rescue Errno::ENOENT
+      raise StandardError, "Not found: #{f}\n#{e}"
+    rescue Exception => e # Whatever was raised, we want it.
+      raise StandardError, "Failed to read as YAML: #{f}\n#{e}"
+    end
+
+    BIN_PREFIX = 'bin:'
+
+    def self.bin_loader(name)
+      return false unless name.downcase.start_with?(BIN_PREFIX)
+      n, _sep, f = name.slice(BIN_PREFIX.size...name.size).partition(':')
+      raise StandardError, 'No name given.' if n.empty?
+      raise StandardError, 'No filename given.' if f.empty?
+      doc = File.binread(f)
+      raise StandardError, "#{name} #{n} exists already." unless Gen.d.add(n, doc)
+      true
+    rescue Errno::ENOENT
+      raise StandardError, "Not found: #{f}\n#{e}"
+    rescue Exception => e # Whatever was raised, we want it.
+      raise StandardError, "Failed to read #{f}\n#{e}"
+    end
+
+    CONFIG_PREFIX = 'config:'
+
+    def self.config_loader(name)
+      return false unless name.downcase.start_with?(CONFIG_PREFIX)
+      raise StandardError, "Config name remains: #{Gen.config}" unless Gen.config.nil?
+      n = name.slice(CONFIG_PREFIX.size...name.size)
+      raise StandardError, 'No name given.' if n.empty?
+      # Interpretation left completely to config loading.
+      Gen.config = n
+      true
+    end
+
+    SEPARATOR_PREFIX = 'separator:'
+
+    def self.separator_loader(name)
+      return false unless name.downcase.start_with?(SEPARATOR_PREFIX)
+      n = name.slice(SEPARATOR_PREFIX.size...name.size)
+      n = nil if n.empty?
+      Gen.separator = n
+      true
+    end
+
+    def self.loaders
+      [
+        method(:req_loader),
+        method(:rereq_loader),
+        method(:ruby_loader),
+        method(:yaml_loader),
+        method(:bin_loader),
+        method(:config_loader),
+        method(:separator_loader)
+      ]
+    end
+
+    def self.document
+      <<EOB
+- #{Loaders::REQ_PREFIX}req_name : requires the gem.
+- #{Loaders::REREQ_PREFIX}code : runs code to add gem tasks again.
+- ruby_file#{Loaders::RUBY_EXT} : changes to Ruby file directory and requires the file.
+- #{Loaders::YAML_PREFIX}name:filename : Loads YAML file into Gen.d.name.
+- name:filename.{#{(Loaders::YAML_EXTS.map { |s| s[1...s.size] }).join('|')}} : Loads YAML file into Gen.d.name.
+- #{Loaders::BIN_PREFIX}name:filename : Loads binary file into Gen.d.name.
+- #{Loaders::CONFIG_PREFIX}name : Sets Gen.config for next gem/Ruby file configuration loading.
+- #{Loaders::SEPARATOR_PREFIX}string : Sets Gen.separator to string.
+EOB
+    end
+  end
+end

data/lib/openapi/sourcetools/output.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+
+module OpenAPISourceTools
+  # Output configuration settings for easy storage.
+  # You can have it in configuration and pass hash to initialize.
+  class OutputConfiguration
+    attr_reader :indent_character, :indent_step
+    attr_reader :tab, :tab_replaces_count
+
+    def initialize(cfg = {})
+      @indent_character = cfg['indent_character'] || ' '
+      @indent_step = cfg['indent_step'] || 4
+      @tab = cfg['tab'] || "\t"
+      @tab_replaces_count = cfg['tab_replaces_count'] || 0
+    end
+  end
+
+  # Output indentation helper class.
+  # Exposed as Gen.output for use from templates.
+  class Output
+    attr_reader :config
+    attr_accessor :last_indent
+
+    def initialize(cfg = OutputConfiguration.new)
+      @config = cfg
+      @last_indent = 0
+    end
+
+    def config=(cfg)
+      cfg = OutputConfiguration.new(cfg) if cfg.is_a?(Hash)
+      raise ArgumentError, "Expected OutputConfiguration or Hash, got #{cfg.class}" unless cfg.is_a?(OutputConfiguration)
+      @config = cfg
+      @last_indent = 0
+    end
+
+    # Takes an array of code blocks/lines or integers/booleans and produces
+    # indented output using the separator character.
+    # Set class attributes to obtain desired outcome.
+    def join(blocks, separator = "\n")
+      indented = []
+      blocks.flatten!
+      indent = 0
+      blocks.each do |block|
+        if block.nil?
+          indent = 0
+        elsif block.is_a?(Integer)
+          indent += block
+        elsif block.is_a?(TrueClass)
+          indent += @config.indent_step
+        elsif block.is_a?(FalseClass)
+          indent -= @config.indent_step
+        else
+          block = block.to_s unless block.is_a?(String)
+          if block.empty?
+            indented.push('')
+            next
+          end
+          if indent.zero?
+            indented.push(block)
+            next
+          end
+          if @config.tab_replaces_count.positive?
+            tabs = @config.tab * (indent / @config.tab_replaces_count)
+            chars = @config.indent_character * (indent % @config.tab_replaces_count)
+          else
+            tabs = ''
+            chars = @config.indent_character * indent
+          end
+          lines = block.lines(chomp: true)
+          lines.each do |line|
+            indented.push("#{tabs}#{chars}#{line}")
+          end
+        end
+      end
+      @last_indent = indent
+      indented.join(separator)
+    end
+  end
+end

data/lib/openapi/sourcetools/securityschemes.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'task'
+require 'yaml'
+
+
+module OpenAPISourceTools
+  # Class that contains security scheme objects and what headers
+  # and parameters are added to the request when the scheme is used.
+  class SecuritySchemeInfo
+    include Comparable
+
+    attr_reader :headers, :parameters, :query_parameters, :cookies
+
+    def initialize(security_scheme = {}, scheme_templates = [])
+      @headers = {}
+      @parameters = {}
+      @query_parameters = {}
+      @cookies = {}
+      scheme_templates.each do |template|
+        s = template['scheme']
+        match = true
+        s.each do |k, v|
+          unless v == security_scheme[k]
+            match = false
+            break
+          end
+        end
+        next unless match
+        o = template['output']
+        fill_in(@headers, o['headers'] || {}, security_scheme)
+        fill_in(@parameters, o['parameters'] || {}, security_scheme)
+        fill_in(@query_parameters, o['query_parameters'] || {}, security_scheme)
+        fill_in(@cookies, o['cookies'] || {}, security_scheme)
+        break
+      end
+    end
+
+    def fill_in(output, source, scheme)
+      source.each do |k, v|
+        if k.start_with?('<') && k.end_with?('>')
+          scheme_key = k[1..-2]
+          scheme_value = scheme[scheme_key]
+          raise "Missing security scheme value for #{scheme_key}" if scheme_value.nil?
+          output[scheme_value] = v
+        else
+          output[k] = v
+        end
+      end
+    end
+
+    def merge!(other)
+      @headers.merge!(other.headers)
+      @parameters.merge!(other.parameters)
+      @query_parameters.merge!(other.query_parameters)
+      @cookies.merge!(other.cookies)
+    end
+
+    def merge(other)
+      out = SecuritySchemeInfo.new({}, [])
+      out.merge!(self)
+      out.merge!(other)
+      out
+    end
+
+    def <=>(other)
+      # Only really interested in equality.
+      @headers <=> other.headers || @parameters <=> other.parameters || @query_parameters <=> other.query_parameters || @cookies <=> other.cookies
+    end
+  end
+
+  class ScopedSecuritySchemeInfo
+    include Comparable
+
+    attr_reader :ssi, :scopes
+
+    def initialize(ssi, scopes)
+      @ssi = ssi
+      @scopes = scopes
+    end
+
+    def merge(other)
+      @ssi = @ssi.merge(other.ssi)
+      @scopes = @scopes.concat(other.scopes).uniq
+    end
+
+    def <=>(other)
+      # Only really interested in equality.
+      @ssi <=> other.ssi || @scopes <=> other.scopes
+    end
+  end
+
+  # Helper class for dealing with securitySchemes.
+  # Adds :security key to each operation object and to root.
+  # They contain the used securitySchemes in use and the security schemes
+  # in effect for that operation.
+  class SecuritySchemesTask
+    include TaskInterface
+
+    def default_configuration
+      # type apiKey, name, in.
+      # type http, scheme, bearerFormat.
+      # type mutualTLS, beyond the scope of code templates.
+      # type oauth2, flows object.
+      # type openIdConnect, openIdConnectUrl. More for login?
+      YAML.safe_load(%q(---
+security_schemes:
+- scheme:
+    type: apiKey
+    in: header
+  output:
+    headers:
+      '<name>': string
+- scheme:
+    type: apiKey
+    in: query
+  output:
+    parameters:
+      '<name>': string
+- scheme:
+    type: apiKey
+    in: query
+  output:
+    query_parameters:
+      '<name>': string
+- scheme:
+    type: apiKey
+    in: cookie
+  output:
+    cookies:
+     '<name>': true
+- scheme:
+    type: http
+    scheme: basic
+  output:
+    headers:
+      Authorization: string
+- scheme:
+    type: http
+    scheme: bearer
+  output:
+    headers:
+      Authorization: string
+- scheme:
+    type: mutualTLS
+  output: {}
+- scheme:
+    type: oauth2
+  output:
+    headers:
+      Authorization: string
+- scheme:
+    type: openIdConnect
+  output:
+    headers:
+      Authorization: string
+))
+    end
+
+    def convert_security_schemes(doc)
+      ss = doc.dig('components', 'securitySchemes')
+      return nil if ss.nil?
+      # Should create unique objects. Different name may lead to same object.
+      out = {}
+      ss.each do |name, security_scheme|
+        out[name] = SecuritySchemeInfo.new(security_scheme)
+      end
+      out
+    end
+
+    def operation_object_security(doc, schemes)
+      # Find all operation objects and security in effect.
+      all_ops = []
+      seen_secs = Set.new
+      root_sec = doc['security'] || []
+      not_method = %w[parameters servers summary description]
+      doc['paths'].each_value do |path_item|
+        path_sec = path_item['security'] || root_sec
+        path_item.each do |method, op|
+          next if not_method.include?(method)
+          op_sec = op['security'] || path_sec
+          all_ops.push([ op, op_sec ])
+          op_sec.each do |security_requirement|
+            names = security_requirement.keys
+            seen_secs.merge(names)
+            if names.empty? && !schemes.key?('')
+              schemes[''] = SecuritySchemeInfo.new
+            end
+          end
+        end
+      end
+      # Check that all seen secs names have a scheme. Report all in one place.
+      missing = false
+      seen_secs.to_a.sort!.each do |name|
+        unless schemes.key?(name)
+          missing = true
+          warn("#/components/securitySchemes is missing: #{name}")
+        end
+      end
+      return 1 if missing
+      # Now we know all individual parts are available.
+      # Map security arrays of objects to arrays of arrays.
+      all_scopeds = [] # For having just one instance for unique data combination.
+      all_ops.each do |pair|
+        sec = pair.second.map do |sec_req|
+          keys = sec_req.keys.sort!
+          values = keys.map { |name| sec_req[name].sort! }
+          if keys.empty?
+            keys = [ '' ]
+            values = [ [] ]
+          end
+          s3is = []
+          keys.size.times do |idx|
+            name = keys[idx]
+            scopes = values[idx]
+            s3i = ScopedSecuritySchemeInfo.new(schemes[name], scopes)
+            idx = all_scopeds.index(s3i)
+            if idx.nil?
+              all_scopeds.push(s3i)
+            else
+              s3i = all_scopeds(idx) # Use the same instance everywhere.
+            end
+            s3is.push(s3i)
+          end
+          s3is
+        end
+        pair.first[:security] = sec # Arrays of ScopedSecuritySchemeInfo.
+        # When individual objects are not needed, provide merged together items.
+        all_merged = []
+        pair.first[:security_merged] = sec.map do |s3is| # ScopedSecuritySchemeInfos.
+          m = s3is.first
+          s3is[1..].each do |s3i|
+            m = m.merge(s3i)
+          end
+          idx = all_merged.index(m)
+          if idx.nil?
+            all_merged.push(m)
+          else
+            m = all_merged[idx] # Use the same instance everywhere.
+          end
+          m
+        end
+      end
+      all_merged.map(&:ssi).uniq.sort!
+    end
+
+    def generate(_context_binding)
+      # Get security_schemes from config, append defaults to it.
+      scheme_templates = gen.configuration['security_schemes'] || []
+      scheme_templates.concat(default_configuration['security_schemes'])
+      simple_schemes = convert_security_schemes(Gen.doc)
+      # For all operation objects, add :security array with all used schemes.
+      merged_schemes = operation_object_security(Gen.doc, simple_schemes || {})
+      return merged_schemes if merged_schemes.is_a?(Integer)
+      Gen.doc[:securitySchemes] = simple_schemes unless simple_schemes.nil?
+      Gen.doc[:securitySchemes_merged] = merged_schemes unless merged_schemes.empty?
+    end
+
+    def discard
+      true
+    end
+
+    COMPONENTS = '#/components/'
+  end
+end