openapi-sourcetools 0.7.0 → 0.8.0

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

data/lib/openapi/sourcetools/task.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'common'
+require 'erb'
+
+
+module OpenAPISourceTools
+
+  # Required interface for tasks, with default implementation for some methods.
+  module TaskInterface
+    def generate(context_binding)
+      raise NotImplementedError
+    end
+
+    def output_name
+      raise NotImplementedError
+    end
+
+    def discard
+      false
+    end
+
+    def executable
+      false
+    end
+
+    def system
+      false
+    end
+  end
+
+  # Loads template or takes it as argument. Renders template using ERB.
+  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
+      OpenAPISourceTools::Common.aargh("Template #{n}syntax error: #{e.full_message}", 5)
+    rescue Exception => e # Some unexpected error.
+      OpenAPISourceTools::Common.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
+
+  # A task that provides contents to be written to a named file.
+  # Optionaly the file may be made executable.
+  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
+
+  # Sets Gen.x to empty hash. Inserted after gem tasks.
+  class RestoreProcessorStorage
+    include TaskInterface
+
+    attr_accessor :x # Allows setting the current value when setup code finishes.
+
+    # Sets initial default value.
+    def initialize(x = {})
+      @x = x
+      Gen.x = @x
+    end
+
+    def generate(_context_binding)
+      Gen.x = @x # Restore whatever was current when setup code finished.
+    end
+
+    def discard
+      true
+    end
+
+    def system
+      true
+    end
+  end
+end

data/lib/openapi/sourcetools/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Copyright © 2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+module OpenAPISourceTools
+  NAME = 'openapi-sourcetools'
+  VERSION = '0.8.0'
+
+  def self.info(separator = ': ')
+    "#{NAME}#{separator}#{VERSION}"
+  end
+end

data/lib/openapi/sourcetools.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Copyright © 2024-2025 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative 'sourcetools/task'
+require_relative 'sourcetools/config'
+require_relative 'sourcetools/version'
+# Other modules or classes are exposed via Gen attributes as class instances as needed.
+# Docs is only needed for run-time storage of whatever loaders can handle.
+# Loaders array is exposed and can be added to at run-time.
+# Helper instance is accessible via Gen.h.
+# Output is exposed via Gen.o and Gen.output. Note that if you assign to one,
+# the other will not change.
+# The rest are for internal implementation.

metadata

@@ -1,20 +1,40 @@
 --- !ruby/object:Gem::Specification
 name: openapi-sourcetools
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Ismo Kärkkäinen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-07 00:00:00.000000000 Z
-dependencies: []
-description: |2
+date: 2025-01-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: deep_merge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.2
+description: |-
+  Tools for handling API specification in OpenAPI format.
+  Programs to replace of duplicate definitions with references. Other checks.
 
-  Tools for handling API specification in OpenAPI format. Replacement of
-  duplicate definitions with references. Other checks. Does not validate
-  the document against OpenAPI format specification.
+  Does not validate the document against OpenAPI format specification.
 email: ismokarkkainen@icloud.com
 executables:
 - openapi-addheaders
@@ -41,15 +61,19 @@ files:
 - bin/openapi-merge
 - bin/openapi-modifypaths
 - bin/openapi-processpaths
-- lib/apiobjects.rb
-- lib/common.rb
-- lib/docs.rb
-- lib/gen.rb
-- lib/generate.rb
-- lib/helper.rb
-- lib/loaders.rb
-- lib/output.rb
-- lib/task.rb
+- lib/openapi/sourcetools.rb
+- lib/openapi/sourcetools/apiobjects.rb
+- lib/openapi/sourcetools/common.rb
+- lib/openapi/sourcetools/config.rb
+- lib/openapi/sourcetools/docs.rb
+- lib/openapi/sourcetools/gen.rb
+- lib/openapi/sourcetools/generate.rb
+- lib/openapi/sourcetools/helper.rb
+- lib/openapi/sourcetools/loaders.rb
+- lib/openapi/sourcetools/output.rb
+- lib/openapi/sourcetools/securityschemes.rb
+- lib/openapi/sourcetools/task.rb
+- lib/openapi/sourcetools/version.rb
 homepage: https://xn--ismo-krkkinen-gfbd.fi/openapi-sourcetools/index.html
 licenses:
 - UPL-1.0
@@ -63,14 +87,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.2.5
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.33
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Tools for creating source code from API specification.