openapi-sourcetools 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b790daa9dc40626f360f32ba98853c2b5410e5214d0d2ef32334df1858a9262
-  data.tar.gz: 842e1b54d72995112b38f678f3b0f853d9e0e6ea03652d56797715cb215e2c35
+  metadata.gz: 830a477c8647ad883e5a6619767f19cfae7c2d9b9baa100b0e10bdd911ef0fc1
+  data.tar.gz: 9e4a89d44c344c0099f826bf08c459b2eaa448e4d8b76b982e7ee8b7146199b2
 SHA512:
-  metadata.gz: 5fa1f5ac001251e2d5b56b701bac7d8489efd01fdbbfc2884a0be84c7c5f86dd1a85d1e1cff6120ae09d0d462912711a70ad269d2c5c740c4639a6e495057e78
-  data.tar.gz: ec9dc7d99bfcd12387d163a88c7502052c44cc0159c7bd5865d86a17af0511e979224289ec56f7f049400f4280e02fa583498a553791be9f1b762153cac4b903
+  metadata.gz: eef01e1c3095d747213533d8ceeb4d0ba4107970b6541632b92b9ffaa0a0202d583ec6934f2af4af3dbf0dff4d0344e053bbf9201d8128cd474406fe11a8b308
+  data.tar.gz: 92fcbc4c9128e213ee4d67d7eebe69c5de9f5ef2576a0efdeae33b2f512a786d586e0eebe903fc932b43f59475ecbd780d925263adbd9f5039b113292db8ae97

data/bin/openapi-addschemas

@@ -29,31 +29,39 @@ def replace_inlines(obj, components, top_level_name = nil)
     return true
   end
   # 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.
+  %w[allOf anyOf oneOf items prefixItems additionalProperties unevaluatedItems
+    unevaluatedProperties if then else not
+  ].each do |prop_name|
+    return false unless replace_inlines(obj[prop_name], components)
+  end
+  %w[properties patternProperties dependentSchemas].each do |prop_name|
+    props = obj[prop_name]
+    next if props.nil?
+    props.keys.sort!.each do |name|
+      return false unless replace_inlines(props[name], components)
+    end
+  end
+  looks_like_type = false
+  # required is omitted since it is in schema and in parameters.
+  %w[type items prefixItems properties patternProperties additionalProperties
+    unevaluatedItems unevaluatedProperties enum const minimum maximum multipleOf
+    exclusiveMinimum exclusiveMaximum maxLength minLength pattern maxItems minItems
+    uniqueItems maxContains minContains maxProperties minProperties propertyNames
+    dependentRequired format contentEncoding contentMediaType contentSchema
+  ].each do |kw|
+    if obj.key?(kw)
+      looks_like_type = true
+      break
+    end
+  end
+  unless looks_like_type
+    # Some kind of intermediate-level object.
     (obj.keys.sort! { |a, b| a.to_s <=> b.to_s }).each do |key|
       next if key == 'securitySchemes'
       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'
-    %w[properties patternProperties].each do |prop_name|
-      props = obj.fetch(prop_name, {})
-      props.keys.sort!.each do |name|
-        return false unless replace_inlines(props[name], components)
-      end
-    end
-    return false unless replace_inlines(obj['additionalProperties'], components)
-  end
   r = components.ref_string(top_level_name) || components.reference(obj)
   components.store_anchor(obj, r)
   components.to_reference_object(obj, r) if top_level_name.nil?

data/bin/openapi-order

@@ -0,0 +1,573 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Copyright © 2026 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+require_relative '../lib/openapi/sourcetools/common'
+require_relative '../lib/openapi/sourcetools/order'
+require 'optparse'
+require 'yaml'
+require 'json'
+
+# Functions related to order instructions.
+
+def metadata
+  'openapi-order-metadata'
+end
+
+def metadata_key
+  'key'
+end
+
+def metadata_regexp
+  'regexp'
+end
+
+def default_order_data(order_key, regexp_prefix)
+  <<EOF
+---
+#{metadata}:
+  #{metadata_key}: "#{order_key}"
+  #{metadata_regexp}: "#{regexp_prefix}"
+# Generic orders for any location of a key.
+'**':
+  servers:
+    #{order_key}: &ServerObject_order
+    - url
+    - name
+    - description
+    - variables
+    '*':
+      #{order_key}: &ServerObject
+      - name
+      - description
+      variables:
+        #{order_key}:
+        - '*'
+        '*':
+          #{order_key}: &ServerVariableObject
+          - description
+          - enum
+          - default
+  server: *ServerObject
+  parameters:
+    #{order_key}: &ParameterObject_order
+    - name
+    - in
+    '*': &ParameterObject
+      #{order_key}:
+      - '$ref'
+      - name
+      - in
+      - required
+      - deprecated
+      - description
+      - content
+      - schema
+      - '*'
+      - #{regexp_prefix}^example[s]?$
+  schema: &Schema
+    #{order_key}:
+    - '$ref'
+    - title
+    - description
+    - deprecated
+    - type
+    - format
+    - enum
+    - const
+    - default
+    - readOnly
+    - writeOnly
+    # Numeric types.
+    - minimum
+    - exclusiveMinimum
+    - exclusiveMaximum
+    - maximum
+    - multipleOf
+    # Strings.
+    - minLength
+    - maxLength
+    - pattern
+    # Core.
+    - allOf
+    - anyOf
+    - oneOf
+    - not
+    - if
+    - then
+    - else
+    # Objects.
+    - required
+    - dependentRequired
+    - minProperties
+    - maxProperties
+    - properties
+    - #{regexp_prefix}^.+Properties$
+    - propertyNames
+    - dependentSchemas
+    - discriminator
+    # Arrays.
+    - minItems
+    - maxItems
+    - uniqueItems
+    - items
+    - #{regexp_prefix}^.+Items$
+    - contains
+    - minContains
+    - maxContains
+    # Content
+    - #{regexp_prefix}^content.*$
+    - examples
+    required:
+      #{order_key}:
+      - '*'
+    dependentRequired:
+      #{order_key}:
+      - '*'
+      '*':
+        #{order_key}:
+        - '*'
+  allOf: &Schema_map
+    '*': *Schema
+  anyOf: *Schema_map
+  oneOf: *Schema_map
+  not: *Schema
+  if: *Schema
+  then: *Schema
+  else: *Schema
+  properties: &Schema_ordered_map
+    #{order_key}:
+    - '*'
+    '*': *Schema
+  patternProperties: *Schema_ordered_map
+  additionalProperties: *Schema
+  propertyNames: *Schema
+  items: *Schema
+  contains: *Schema
+  prefixItems: *Schema_map
+  unevaluatedItems: *Schema
+  unevaluatedProperties: *Schema
+  dependentSchemas: *Schema_ordered_map
+  discriminator:
+    #{order_key}:
+    - propertyName
+    - mapping
+    - defaultMapping
+  content:
+    #{order_key}:
+    - '*'
+    '*': &MediaTypeObject
+      #{order_key}:
+      - schema
+      - #{regexp_prefix}.*Schema$
+      - #{regexp_prefix}^(.*E|e)ncoding$
+      - '*'
+      - #{regexp_prefix}^example[s]?$
+  headers: &HeaderObject
+    #{order_key}:
+    - description
+    - required
+    - '*'
+    - schema
+    '*': *ParameterObject
+  responses:
+    #{order_key}:
+    - '*'
+    - default
+    '*': &ResponseObject
+      #{order_key}:
+      - '$ref'
+      - summary
+      - description
+      - headers
+      - content
+      - links
+  links:
+    #{order_key}:
+    - '*'
+    '*': &LinkObject
+      #{order_key}:
+      - description
+      - #{regexp_prefix}^operation.*
+      - parameters
+      - requestBody
+  requestBody: &RequestBodyObject
+    #{order_key}:
+    - description
+    - required
+    - content
+  security:
+    #{order_key}: &SecurityRequirementObject_order
+    - '*'
+  webhooks:
+    #{order_key}:
+    - '*'
+    '*': &PathItemObject
+      #{order_key}:
+      - '$ref'
+      - summary
+      - description
+      - servers
+      - parameters
+      - '*'
+      - additionalOperations
+      '*':
+        #{order_key}: &OperationObject
+        - '$ref'
+        - operationId
+        - summary
+        - description
+        - parameters
+        - requestBody
+        - responses
+      additionalOperations:
+        #{order_key}:
+        - '*'
+        '*': *OperationObject
+  callbacks:
+    #{order_key}:
+    - '*'
+    '*': *PathItemObject
+#{order_key}:
+- openapi
+- '$self'
+- jsonSchemaDialect
+- info
+- servers
+- '*'
+- paths
+- components
+info:
+  #{order_key}:
+  - title
+  - version
+  - summary
+  - description
+  - contact
+  - license
+  - termsOfService
+  contact:
+    #{order_key}:
+    - name
+  license:
+    #{order_key}:
+    - name
+servers:
+  #{order_key}: *ServerObject_order
+  '*': *ServerObject
+security:
+  #{order_key}: *SecurityRequirementObject_order
+tags: # Do not order tags array but do order Tag Objects.
+  '*':
+    #{order_key}:
+    - name
+    - summary
+    - description
+paths:
+  #{order_key}:
+  - '*'
+  '*': *PathItemObject
+components:
+  #{order_key}:
+  - schemas
+  - '*'
+  - securitySchemes
+  - links
+  - callbacks
+  - examples
+  # Regular expressions are for names from various openapi-add* programs.
+  # Variations for number of digits ensure ordering by number.
+  schemas:
+    #{order_key}:
+    - '*'
+    - #{regexp_prefix}^Schema[0-9]{1}x$
+    - #{regexp_prefix}^Schema[0-9]{2}x$
+    - #{regexp_prefix}^Schema[0-9]{3,}x$
+    '*': *Schema
+  responses:
+    #{order_key}:
+    - '*'
+    - #{regexp_prefix}^Response[0-9]{1}x$
+    - #{regexp_prefix}^Response[0-9]{2}x$
+    - #{regexp_prefix}^Response[0-9]{3,}x$
+    '*': *ResponseObject
+  parameters:
+    #{order_key}:
+    - '*'
+    - #{regexp_prefix}^Parameter[0-9]{1}x$
+    - #{regexp_prefix}^Parameter[0-9]{2}x$
+    - #{regexp_prefix}^Parameter[0-9]{3,}x$
+    '*': *ParameterObject
+  requestBodies:
+    #{order_key}:
+    - '*'
+    - #{regexp_prefix}^RequestBody[0-9]{1}x$
+    - #{regexp_prefix}^RequestBody[0-9]{2}x$
+    - #{regexp_prefix}^RequestBody[0-9]{3,}x$
+    '*': *RequestBodyObject
+  headers:
+    #{order_key}:
+    - '*'
+    - #{regexp_prefix}^Header[0-9]{1}x$
+    - #{regexp_prefix}^Header[0-9]{2}x$
+    - #{regexp_prefix}^Header[0-9]{3,}x$
+    '*': *HeaderObject
+  securitySchemes:
+    #{order_key}:
+    - '*'
+  links:
+    #{order_key}:
+    - '*'
+    '*': *LinkObject
+  callbacks:
+    #{order_key}:
+    - '*'
+    '*': *PathItemObject
+  pathItems:
+    #{order_key}:
+    - '*'
+    '*': *PathItemObject
+  mediaTypes:
+    #{order_key}:
+    - '*'
+    - #{regexp_prefix}^MediaType[0-9]{1}x$
+    - #{regexp_prefix}^MediaType[0-9]{2}x$
+    - #{regexp_prefix}^MediaType[0-9]{3,}x$
+    '*': *MediaTypeObject
+  examples:
+    #{order_key}:
+    - '*'
+EOF
+end
+
+def default_order(order_key, regexp_prefix)
+  YAML.load(default_order_data(order_key, regexp_prefix), aliases: true)
+end
+
+# This needs to extract all path/order pairs, store and sort.
+
+def extract_orders(path, order, collection, order_key, regexp_prefix)
+  return true unless order.is_a?(Hash)
+  order.each do |key, value|
+    if key == order_key
+      unless value.is_a?(Array)
+        OpenAPISourceTools::Common.aargh("Not an array: #{path.join('.')}.#{order_key} =\n#{YAML.dump(value)}")
+        return false
+      end
+      value.each_with_index do |v, k|
+        next if v.is_a?(String)
+        OpenAPISourceTools::Common.aargh("Not a string: #{path}.#{order_key}[#{k}] =\n#{YAML.dump(v)}")
+        return false
+      end
+      key_path = OpenAPISourceTools::Ordering::KeyPath.new(path, regexp_prefix)
+      key_order = OpenAPISourceTools::Ordering::Order.new(value, regexp_prefix)
+      collection.push(OpenAPISourceTools::Ordering::KeyPathOrder.new(key_path, key_order))
+    else
+      key = key.to_s unless key.is_a?(String)
+      path.push(key)
+      return false unless extract_orders(path, value, collection, order_key, regexp_prefix)
+      path.pop
+    end
+  end
+end
+
+# Functions related to applying the order to the document.
+
+def reorder(orders, path, item)
+  return false unless OpenAPISourceTools::Ordering::Order.orderable?(item)
+  orders.each do |order|
+    next unless order.path.match?(path)
+    order.order.apply(item)
+    break
+  end
+  true
+end
+
+def order_document(orders, path, item)
+  return unless reorder(orders, path, item) # Scalars do not pass.
+  if item.is_a?(Array)
+    item.each_with_index do |element, idx|
+      # This needs something and using index as string matches the '*'
+      # used when elements of the array are meant to be processed. By
+      # using the index alone, the '*' can be replaced by a regular
+      # expression that matches specific indices, if so desired.
+      path.push(idx.to_s)
+      order_document(orders, path, element)
+      path.pop
+    end
+  else
+    item.each do |key, value|
+      key = key.to_s unless key.is_a?(String)
+      path.push(key)
+      order_document(orders, path, value)
+      path.pop
+    end
+  end
+end
+
+# Functions related to saving the output.
+
+def to_json(doc, _line_width)
+  JSON.dump(doc)
+end
+
+def to_pretty_json(doc, _line_width)
+  JSON.pretty_generate(doc)
+end
+
+def to_yaml(doc, line_width)
+  YAML.dump(doc, line_width: line_width)
+end
+
+def main
+  input_name = nil
+  output_name = nil
+  order_name = nil
+  order_key = 'x-order'
+  regexp_prefix = 're:'
+  format = 'yaml'
+  formats = {
+    'yaml' => method(:to_yaml),
+    'json' => method(:to_json),
+    'pretty_json' => method(:to_pretty_json)
+  }
+  line_width = 80
+  output_default = false
+
+  parser = OptionParser.new do |opts|
+    opts.summary_indent = '  '
+    opts.summary_width = 20
+    opts.banner = 'Usage: openapi-order [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('--order FILE', 'Read order instructions from FILE.') do |f|
+      order_name = f
+    end
+    opts.on('-f', '--format FORMAT', "Output format: #{formats.keys.sort!.join(', ')}, default: #{format}") do |f|
+      unless formats.key?(f.downcase)
+        exit(OpenAPISourceTools::Common.aargh("Unknown format: #{f}", 1))
+      end
+      format = f
+    end
+    opts.on('-w', '--width WIDTH', "Set YAML line width, default: #{line_width}") do |w|
+      line_width = w.to_i
+    end
+    opts.separator ''
+    opts.separator 'Order options:'
+    opts.on('--default', 'Output default order to --output, ignore input.') do
+      output_default = true
+    end
+    opts.on('-k', '--key KEY', "Use KEY as default order key, default: #{order_key}") do |k|
+      order_key = k
+    end
+    opts.on('-r', '--regexp PREFIX', "Use PREFIX to indicate regular expression, default: #{regexp_prefix}") do |p|
+      regexp_prefix = p
+    end
+    opts.on('-h', '--help', 'Print this help and exit.') do
+      $stdout.puts %(#{opts}
+Loads YAML document and applies ordering to object keys, and arrays with
+objects, when an order matches the key path to object.
+
+Can be used on generic YAML or JSON files. Default order is for OpenAPI
+documents.
+
+The order instructions key "#{order_key}" value must be an array of strings.
+The values can be any combination of the following:
+- Literal key name.
+- Regular expression starting with "#{regexp_prefix}".
+- "*" that matches any key that does not match anything else.
+First match against a value determines the position, and "*" receives all
+unmatched keys. If order array has no "*", every unmatched key will be placed
+last. Only the first "*" has any effect. Multiple keys placed in the same
+position are sorted within that position.
+
+The path to the "#{order_key}" can have any combination of the following:
+- Literal key name.
+- Regular expression starting with "#{regexp_prefix}".
+- "*" that matches one key of any value.
+- "**" that matches one or more keys of any value.
+The path is used to determine if a value in the document should be ordered
+using the instructions. At top level the path is empty and applies to the root
+of the document. Long paths are considered to be more specific than short
+paths, because they supposedly contain more literal keys or limiting regular
+expressions so thay are intended for a specific case. Of paths of same length
+one with "**" is considered less specific than one without.
+
+The path to a value in the document is matched against paths to "#{order_key}"
+to find the most specific order. For elements in an array, the last item in
+the path is the element index as a string. Hence you can use a "*" parallel
+to "#{order_key}" to match any index, but also literals or regular expressions
+to match specific index can be used.
+
+For object value in the document, the order is used to sort the keys of the
+object. Absence of a key in the object has no effect. Any non-string key is
+converted to string for ordering purposes. Original keys are retained.
+
+For array value in the document, the order is used to select values of keys
+from array elements to use in comparison for sorting the array.
+- Using known object property names is recommended.
+- Values of keys should be scalars and have the same type for same key.
+- Missing key places the element after one that has the key.
+- Object and array values are considered to be a missing value.
+- Elements that are not objects end up last because they have no keys.
+Mixture of objects, arrays, and scalars is not expected in the intended use.
+
+Scalar value in the document is not affected.
+
+Non-string keys in the document and order paths are converted to strings for
+processing.
+
+The --key, --regexp, --format, and --output apply to --default output. If
+format is YAML, the internal YAML document is output as is.
+
+To avoid errors, the value of --key should not appear in the document so that
+it only appears as order instructions key in the order document.
+
+In case the document has a key that starts with "#{regexp_prefix}" you can change it in the
+order file or use "#{regexp_prefix}^#{regexp_prefix}the_rest$" as an anchored regular
+expression that only matches the key. The ":" is part of the prefix itself,
+so provide it if you want to keep it. Useful for readability.
+
+When reading an order file, --key and --regexp are over-ridden by root-level
+object "#{metadata}" keys "#{metadata_key}" and "#{metadata_regexp}" values.
+)
+      exit 0
+    end
+  end
+  parser.order!
+
+  if output_default
+    if format == 'yaml'
+      doc = default_order_data(order_key, regexp_prefix)
+    else
+      doc = default_order(order_key, regexp_prefix)
+      doc = formats[format].call(doc, line_width)
+    end
+  else
+    doc = OpenAPISourceTools::Common.load_source(input_name)
+    return 2 if doc.nil?
+
+    order = order_name.nil? ? default_order(order_key, regexp_prefix) : OpenAPISourceTools::Common.load_source(order_name)
+    return 4 if order.nil?
+    md = order.fetch(metadata, {})
+    order_key = md.fetch(metadata_key, order_key)
+    regexp_prefix = md.fetch(metadata_regexp, regexp_prefix)
+    path_orders = []
+    return 4 unless extract_orders([], order, path_orders, order_key, regexp_prefix)
+    path_orders.sort!.reverse! # Longest key pattern sequence first.
+    order_document(path_orders, [], doc)
+    doc = formats[format].call(doc, line_width)
+  end
+
+  OpenAPISourceTools::Common.dump_result(output_name, doc, 3)
+end
+
+exit(main) if File.basename(__FILE__) == File.basename($PROGRAM_NAME)

data/lib/openapi/sourcetools/config.rb

@@ -87,6 +87,10 @@ module OpenAPISourceTools
         return d unless d.zero?
         @path <=> other.path
       end
+
+      def to_s
+        "Root: #{@root} [#{@keys.join(', ')}] #{@path}"
+      end
     end
 
     def self.prepare_prefix(name_prefix, root)

data/lib/openapi/sourcetools/order.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+# Copyright © 2026 Ismo Kärkkäinen
+# Licensed under Universal Permissive License. See LICENSE.txt.
+
+# Top-level module.
+module OpenAPISourceTools
+  # Ordering methods and classes for openapi-order.
+  module Ordering
+    # Used as replacement for '*'.
+    ANY = Regexp.new('^.*$')
+
+    def self.array_item_compare(a, b)
+      a[:values].size.times do |k|
+        av = a[:values][k]
+        bv = b[:values][k]
+        if av.nil?
+          return 1 unless bv.nil?
+        else
+          return -1 if bv.nil?
+          r = av <=> bv
+          return r unless r.nil? || r.zero?
+        end
+      end
+      0
+    end
+
+    # Allowed keys starting from root, with pattern, any or multiple any key.
+    # Initialized with the path to the order array.
+    class KeyPath
+      include Comparable
+
+      attr_reader :items, :multiple, :first_multiple
+
+      # the parent_keys is processed to an array of regular expressions and :multi.
+      # A '*' is eventually replaced with regular expression that accepts anything.
+      # A '**' is replaced by :multi that matches at least one key during match.
+      # A string starting with regexp_prefix is changed to a regular expression.
+      # Other string is turned to anchored regular expression that matches only the string.
+      # The order of '*' and '**' can be modified to minimize occurrences of :multi.
+      def initialize(parent_keys, regexp_prefix)
+        @multiple = false
+        @items = []
+        parent_keys.each do |key|
+          if key == '*'
+            if @items.last == :multi
+              # :multi, :one is same as :one, :multi as at least 2 arbitrary items.
+              @items.pop
+              @items.push(:one, :multi)
+            else
+              @items.push(:one)
+            end
+          elsif key == '**'
+            @multiple = true
+            if @items.last == :multi
+              # :multi, :multi is same as :one, :multi as at least 2 arbitrary items.
+              @items.pop
+              @items.push(:one, :multi)
+            else
+              @items.push(:multi)
+            end
+          elsif key.start_with?(regexp_prefix)
+            @items.push(Regexp.new(key[regexp_prefix.size..]))
+          else
+            @items.push(Regexp.new("^#{Regexp.escape(key)}$"))
+          end
+        end
+        @items.each_with_index do |item, idx|
+          @items[idx] = ANY if item == :one
+        end
+        @first_multiple = @items.index(:multi) || @items.size
+      end
+
+      # Finds indexes of regular expressions that match key, skipping given number.
+      def matching_item_indexes(key, skip_non_multis)
+        indexes = []
+        ([skip_non_multis, @first_multiple].min...@items.size).each do |idx|
+          item = @items[idx]
+          indexes.push(idx) if item == :multi || item.match?(key)
+        end
+        indexes
+      end
+
+      # Given possible matches, uses position_index to check for matches relevant
+      # to the current situation and checks recursively if a solution ending to
+      # the desired point can be found.
+      def search(index_arrays, array_index, position_index)
+        if array_index == index_arrays.size
+          # Last key is known to match last item, so if that were tested, it would pass.
+          return position_index == @items.size - 1
+        end
+        if @items[position_index] == :multi
+          # Multi absorbs current key and releases to next position.
+          return true if search(index_arrays, array_index + 1, position_index + 1)
+          # Multi absorbs current key and stays for more.
+          search(index_arrays, array_index + 1, position_index)
+        else
+          # Only current item to match with.
+          return false if index_arrays[array_index].index(position_index).nil?
+          search(index_arrays, array_index + 1, position_index + 1)
+        end
+      end
+
+      # Performs base checks whether match is possible and if so, obtains indexes
+      # od matching patterns and starts search using those.
+      def match?(key_path)
+        return true if @items.empty? && key_path.empty?
+        slack = key_path.size - @items.size
+        return false if slack.negative? # Path too short.
+        return false if slack.positive? && !@multiple # Path too long.
+        # Last key must match last item.
+        return false unless @items.last == :multi || @items.last.match?(key_path.last)
+        # First key must match first item.
+        return false unless @items.first == :multi || @items.first.match?(key_path.first)
+        return true if key_path.size <= 2 # Tested both already.
+        # Form arrays of possible match indexes for search. Omit first and last.
+        index_arrays = []
+        (1...(key_path.size - 1)).each do |idx|
+          key = key_path[idx]
+          idxs = matching_item_indexes(key, idx)
+          return false if idxs.empty?
+          index_arrays.push(idxs)
+        end
+        search(index_arrays, 0, @items.first == :multi ? 0 : 1)
+      end
+
+      def <=>(other)
+        # The purpose is to place longest "exact" items to the end.
+        # Hence items.size, and the more multiple, the earlier.
+        d = @items.size <=> other.items.size
+        return d unless d.zero?
+        -@items.count(:multi) <=> -other.items.count(:multi)
+      end
+    end
+
+    # Book-keeping class for pattern and its location.
+    class KeyPattern
+      attr_reader :pattern, :index, :priority
+
+      def initialize(pattern, index, priority)
+        @pattern = pattern
+        @index = index
+        @priority = priority
+      end
+
+      def match?(string)
+        @pattern.match?(string)
+      end
+
+      def any?
+        @index != @priority
+      end
+    end
+
+    # Handles ordering keys or an array using the given key order.
+    class Order
+      def self.orderable?(item)
+        return true if item.is_a?(Hash)
+        return true if item.is_a?(Array)
+        false
+      end
+
+      attr_reader :patterns
+
+      def initialize(keys, regexp_prefix)
+        @patterns = []
+        has_asterisk = false
+        keys.each_with_index do |string, idx|
+          if string.start_with?(regexp_prefix)
+            @patterns.push(KeyPattern.new(Regexp.new(string[regexp_prefix.size..]), idx, idx))
+          elsif string == '*'
+            @patterns.push(KeyPattern.new(Regexp.new('^.*$'), idx, keys.size)) unless has_asterisk # First used.
+            has_asterisk = true
+          else
+            @patterns.push(KeyPattern.new(Regexp.new("^#{Regexp.escape(string)}$"), idx, idx))
+          end
+        end
+        @patterns.push(KeyPattern.new(Regexp.new('^.*$'), @patterns.size, keys.size + 1)) unless has_asterisk
+      end
+
+      def apply_array(array)
+        return true if array.size < 2
+        values = []
+        array.each do |item|
+          amended = {
+            item: item,
+            values: []
+          }
+          unless item.is_a?(Hash)
+            amended[:values] = Array.new(@patterns.size, nil)
+            values.push(amended)
+            next
+          end
+          @patterns.each do |kp|
+            if kp.any?
+              amended[:values].push(nil)
+              next
+            end
+            # Find first matching key.
+            v = nil
+            item.each_key do |item_key|
+              next unless kp.match?(item_key)
+              v = item[item_key]
+              break
+            end
+            amended[:values].push((v.is_a?(Array) || v.is_a?(Hash)) ? nil : v)
+          end
+          values.push(amended)
+        end
+        values.sort! { |a, b| OpenAPISourceTools::Ordering.array_item_compare(a, b) }
+        values.each_with_index { |amended, i| array[i] = amended[:item] }
+        true
+      end
+
+      def apply_hash(hash)
+        return true if hash.size < 2
+        groups = @patterns.map do |kp|
+          {
+            kp: kp,
+            keys: []
+          }
+        end
+        s2orig = {}
+        hash.each_key do |key|
+          skey = key.is_a?(String) ? key : key.to_s
+          s2orig[skey] = key
+          best_priority = groups.size + 1
+          best_idx = nil
+          groups.each do |group|
+            kp = group[:kp]
+            next if best_priority <= kp.priority
+            next unless kp.match?(skey)
+            best_priority = kp.priority
+            best_idx = kp.index
+          end
+          groups[best_idx][:keys].push(skey) unless best_idx.nil?
+        end
+        ordered = {}
+        groups.each do |group|
+          group[:keys].sort!
+          group[:keys].each { |k| ordered[s2orig[k]] = hash[s2orig[k]] }
+        end
+        hash.clear
+        hash.merge!(ordered)
+        true
+      end
+
+      def apply(item)
+        return apply_array(item) if item.is_a?(Array)
+        return apply_hash(item) if item.is_a?(Hash)
+        false
+      end
+    end
+
+    # Holds KeyPath and the order that was specified.
+    class KeyPathOrder
+      include Comparable
+
+      attr_reader :path, :order
+
+      def initialize(key_path, order)
+        @path = key_path
+        @order = order
+      end
+
+      def <=>(other)
+        @path <=> other.path
+      end
+    end
+  end
+end

data/lib/openapi/sourcetools/version.rb

@@ -5,7 +5,7 @@
 
 module OpenAPISourceTools
   NAME = 'openapi-sourcetools'
-  VERSION = '0.11.0'
+  VERSION = '0.12.0'
 
   def self.info(separator = ': ')
     "#{NAME}#{separator}#{VERSION}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi-sourcetools
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Ismo Kärkkäinen
@@ -47,6 +47,7 @@ executables:
 - openapi-generate
 - openapi-merge
 - openapi-modifypaths
+- openapi-order
 - openapi-patterntests
 - openapi-processpaths
 extensions: []
@@ -64,6 +65,7 @@ files:
 - bin/openapi-generate
 - bin/openapi-merge
 - bin/openapi-modifypaths
+- bin/openapi-order
 - bin/openapi-patterntests
 - bin/openapi-processpaths
 - lib/openapi/sourcetools.rb
@@ -75,6 +77,7 @@ files:
 - lib/openapi/sourcetools/generate.rb
 - lib/openapi/sourcetools/helper.rb
 - lib/openapi/sourcetools/loaders.rb
+- lib/openapi/sourcetools/order.rb
 - lib/openapi/sourcetools/output.rb
 - lib/openapi/sourcetools/task.rb
 - lib/openapi/sourcetools/version.rb
@@ -90,7 +93,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.5
+      version: 3.3.11
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="