tomograph 3.2.7 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df200f372e9f0e40bb72b2fb5bda369f79519b3081ce0d562f172d91011328ae
-  data.tar.gz: c34517a4d760e0ed3412663976744e4200f7e2bc5b1171d07e96fb7d8d279be6
+  metadata.gz: 97a07b518360a088260ba2e9ead6ece87b10235bb7766490bc659277387ef9bc
+  data.tar.gz: 239ed051e682a6ea540dc9579f3d58c75594b3a89f4c9ad0fd8c3c4c4ee1b0ae
 SHA512:
-  metadata.gz: 3cfe0cc68a80c58eb6f0a1da50cf36f3f4ce30497be8b3c0f639d3922a9ecf4ef2afe52ce04c5e9267361233628f432b19f72fd39deee74aa0e3fa7ffec67868
-  data.tar.gz: 0df481b090aaf42a50c10eec7ffafe2e04077432de5e89ab1c8041a276a4095e01e2fe510f40fa34c0e6baae33d3dcf2229a194d4cfdfc26e6e2c081283f9404
+  metadata.gz: adc5d107c07a96565b5ed80d1a6f4ee5069c5ce1785ffa23230494537e73950c24c9455466a30dfd3921575f1c04f81d37bb64037147ff3856cab4570c8ad416
+  data.tar.gz: 48260bf6279100f0972b53e1a5192242361c487ffccec6b8d5bf234b1cd2bf1ed72c9a08047d08b54988cf03e80feac54e17b1bc7ab58a49c4b1d3e638fddcc7

data/.github/workflows/ruby.yml

@@ -26,7 +26,7 @@ jobs:
       uses: ruby/setup-ruby@v1
     # uses: ruby/setup-ruby@ec106b438a1ff6ff109590de34ddc62c540232e0
       with:
-        ruby-version: 2.7
+        ruby-version: '3.0'
     - name: Install dependencies
       run: bundle install
     - name: Run tests

data/.rubocop.yml

@@ -1,5 +1,6 @@
 AllCops:
-  TargetRubyVersion: 2.4
+  TargetRubyVersion: 3.0
+  NewCops: disable
 
 Layout/LineLength:
   Max: 120
@@ -30,3 +31,9 @@ Metrics/AbcSize:
 
 Metrics/ClassLength:
   Max: 150
+
+Metrics/CyclomaticComplexity:
+  Max: 16
+
+Metrics/PerceivedComplexity:
+  Max: 18

data/.tool-versions

@@ -1,2 +1,2 @@
-ruby 2.7.1
+ruby 3.0.2
 nodejs 11.3.0

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Change log
 
+### 4.0.0 - 2026-11-03
+
+* breaking changes
+  * require Ruby 3.0 or newer; Ruby 2.x is no longer supported
+* features
+  * resolve external OpenAPI 3 path and component references
+  * support multipart and form-urlencoded request schemas
+* bug fixes
+  * include referenced component schemas in composed response schemas
+  * convert OpenAPI nullable fields to JSON Schema null types
+  * ignore path-level parameters when collecting operations
+  * preserve optional empty response bodies through `x-empty-body`
+* maintenance
+  * align local Ruby version managers and CI on Ruby 3.0.2
+  * update RuboCop target Ruby version and complexity limits
+
 ### 3.2.7 - 2024-12-08
 
 * bug fixes

data/README.md

@@ -371,6 +371,15 @@ Exclude "description" keys from json-schemas.
 tomograph -d 4 apielemetns.yaml doc.json --exclude-description
 ```
 
+#### json-schema-draft4
+
+Add `"$schema": "http://json-schema.org/draft-04/schema#"` to every non-empty request and response body.
+Empty bodies stay `{}`.
+
+```bash
+tomograph -d openapi3 openapi3.yaml doc.json --json-schema-draft4
+```
+
 #### split
 
 Split output into files by method. Output in dir path.

data/exe/tomograph

@@ -17,6 +17,7 @@ description 'Converts API Blueprint to JSON Schema'
 on('-d DRAFTER_VERSION', '--drafter', 'Choose drafter version: crafter or 4,
     or OpenAPI version: openapi2 or openapi3. Default: use drafter v.4.')
 on('--exclude-description', 'Exclude "description" keys.')
+on('--json-schema-draft4', 'Add "$schema": draft-04 to every non-empty request and response body.')
 on('--split', 'Split output into files by method.')
 arg :input, 'path/to/doc.yaml (API Elements)'
 arg :output, 'path/to/doc.json or path/to/dir if --split is used.'
@@ -30,6 +31,21 @@ def prune!(obj, unwanted_key)
   end
 end
 
+JSON_SCHEMA_DRAFT4 = 'http://json-schema.org/draft-04/schema#'.freeze
+
+def with_draft4(schema)
+  return schema unless schema.is_a?(Hash) && !schema.empty?
+
+  { '$schema' => JSON_SCHEMA_DRAFT4 }.merge(schema)
+end
+
+def add_draft4!(actions)
+  actions.each do |action|
+    action['requests'] = action['requests'].map { |request| with_draft4(request) }
+    action['responses'].each { |response| response['body'] = with_draft4(response['body']) }
+  end
+end
+
 def choose_drafter(opt_parser)
   case opt_parser
   when 'crafter'
@@ -80,6 +96,7 @@ main do |input, output|
   actions = tomogram.to_a.map(&:to_hash)
 
   prune!(actions, 'description') if options['exclude-description']
+  add_draft4!(actions) if options['json-schema-draft4']
 
   if options['split']
     write_split_json(actions, output)

data/lib/tomograph/openapi/external_ref_resolver.rb

@@ -0,0 +1,170 @@
+require 'yaml'
+
+module Tomograph
+  module OpenApi
+    # Loads an OpenAPI document and rewrites external $ref (./paths/auth.yaml,
+    # ../components/schemas.yaml#/LoginRequest) into internal #/components/... pointers.
+    class ExternalRefResolver
+      COMPONENT_KINDS = {
+        'schema' => 'schemas',
+        'schemas' => 'schemas',
+        'response' => 'responses',
+        'responses' => 'responses',
+        'parameter' => 'parameters',
+        'parameters' => 'parameters'
+      }.freeze
+
+      def self.load(path)
+        new.load(path)
+      end
+
+      def initialize
+        @cache = {}
+        @registered = {}
+        @stack = []
+        @components = {
+          'schemas' => {},
+          'responses' => {},
+          'parameters' => {}
+        }
+      end
+
+      def load(path)
+        path = File.expand_path(path)
+        resolved = resolve_node(read_yaml(path), File.dirname(path))
+        merge_components(resolved)
+      end
+
+      private
+
+      def merge_components(doc)
+        @components.each do |kind, values|
+          next if values.empty?
+
+          doc['components'] ||= {}
+          doc['components'][kind] = values.merge(doc['components'][kind] || {})
+        end
+        doc
+      end
+
+      def resolve_node(node, base_dir)
+        case node
+        when Hash
+          resolved = {}
+          node.each { |key, value| resolved[key] = resolve_node(value, base_dir) }
+          ref = node['$ref']
+          return resolved unless ref.is_a?(String) && external_ref?(ref)
+
+          target = resolve_external(ref, base_dir)
+          extra = resolved.reject { |key, _| key == '$ref' }
+          target.is_a?(Hash) ? target.merge(extra) : target
+        when Array
+          node.map { |value| resolve_node(value, base_dir) }
+        else
+          node
+        end
+      end
+
+      def resolve_external(ref, base_dir)
+        abs_ref = absolute_ref(ref, base_dir)
+        return { '$ref' => ref } if @stack.include?(abs_ref)
+
+        @stack.push(abs_ref)
+        begin
+          file, fragment = split_external(ref, base_dir)
+          data = read_yaml(file)
+          segments = pointer_segments(fragment)
+          kind = component_kind(file)
+          if kind && segments.length == 1 && data.is_a?(Hash) && data.key?(segments[0])
+            register_component_file(file, kind, data)
+            { '$ref' => "#/components/#{kind}/#{segments[0]}" }
+          else
+            target = segments.empty? ? data : dig_pointer(data, segments)
+            resolve_node(deepcopy(target), File.dirname(file))
+          end
+        ensure
+          @stack.pop
+        end
+      end
+
+      def register_component_file(file, kind, data)
+        return if @registered[file]
+
+        @registered[file] = true
+        names = data.keys
+        names.each do |name|
+          rewritten = rewrite_local_refs(deepcopy(data[name]), names, kind)
+          @components[kind][name] = resolve_node(rewritten, File.dirname(file))
+        end
+      end
+
+      def rewrite_local_refs(node, names, kind)
+        case node
+        when Hash
+          node.each_with_object({}) do |(key, value), result|
+            if key == '$ref' && local_component_ref?(value, names)
+              result[key] = "#/components/#{kind}/#{value[2..-1]}"
+            else
+              result[key] = rewrite_local_refs(value, names, kind)
+            end
+          end
+        when Array
+          node.map { |value| rewrite_local_refs(value, names, kind) }
+        else
+          node
+        end
+      end
+
+      def local_component_ref?(value, names)
+        value.is_a?(String) && value =~ /\A#\/([^\/]+)\z/ && names.include?(value[2..-1])
+      end
+
+      def external_ref?(ref)
+        !ref.start_with?('#')
+      end
+
+      def absolute_ref(ref, base_dir)
+        file, fragment = ref.split('#', 2)
+        "#{File.expand_path(file, base_dir)}##{fragment}"
+      end
+
+      def split_external(ref, base_dir)
+        file, fragment = ref.split('#', 2)
+        [File.expand_path(file, base_dir), fragment]
+      end
+
+      def component_kind(path)
+        COMPONENT_KINDS[File.basename(path, '.*')]
+      end
+
+      def pointer_segments(fragment)
+        return [] if fragment.nil? || fragment.empty? || fragment == '/'
+
+        fragment.sub(%r{\A/}, '').split('/').map { |segment| segment.gsub('~1', '/').gsub('~0', '~') }
+      end
+
+      def dig_pointer(data, segments)
+        segments.reduce(data) do |memo, segment|
+          case memo
+          when Hash then memo[segment]
+          when Array then memo[segment.to_i]
+          end
+        end
+      end
+
+      def read_yaml(path)
+        return @cache[path] if @cache.key?(path)
+
+        @cache[path] = YAML.safe_load(File.read(path)) || {}
+      end
+
+      def deepcopy(obj)
+        case obj
+        when Hash then obj.each_with_object({}) { |(key, value), copy| copy[key] = deepcopy(value) }
+        when Array then obj.map { |value| deepcopy(value) }
+        else obj
+        end
+      end
+    end
+  end
+end

data/lib/tomograph/openapi/openapi3.rb

@@ -1,25 +1,33 @@
 require 'tomograph/tomogram/action'
+require 'tomograph/openapi/external_ref_resolver'
 
 module Tomograph
   module OpenApi
     class OpenApi3
+      HTTP_METHODS = %w[get put post delete options head patch trace].freeze
+      REQUEST_SCHEMA_TYPES = ['application/json', 'multipart/form-data', 'application/x-www-form-urlencoded'].freeze
+
       def initialize(prefix, openapi3_yaml_path)
         @prefix = prefix
-        @documentation = YAML.safe_load(File.read(openapi3_yaml_path))
+        @documentation = ExternalRefResolver.load(openapi3_yaml_path)
       end
 
       def to_tomogram
         @tomogram ||= @documentation['paths'].each_with_object([]) do |(path, action_definition), result|
-          action_definition.keys.each do |method|
-            ajj = valuekey(action_definition[method]['requestBody'], 'content')
-            aj = valuekey(ajj, 'application/json')
+          next unless action_definition.is_a?(Hash)
+
+          action_definition.each do |method, operation|
+            next unless HTTP_METHODS.include?(method)
+            next unless operation.is_a?(Hash)
 
+            request_body = operation['requestBody']
+            content = valuekey(request_body, 'content')
             result.push(Tomograph::Tomogram::Action.new(
                           path: "#{@prefix}#{path}",
                           method: method.upcase,
-                          content_type: action_definition[method]['requestBody'].nil? ? nil : action_definition[method]['requestBody']['content'].keys[0],
-                          requests: [schema_new(valuekey(aj, 'schema'), @documentation['definitions'])].compact,
-                          responses: responses(action_definition[method]['responses']),
+                          content_type: request_body.nil? ? nil : content&.keys&.first,
+                          requests: [request_schema(content)].compact,
+                          responses: responses(operation['responses']),
                           resource: ''
                         ))
           end
@@ -30,8 +38,29 @@ module Tomograph
         value.nil? ? nil : value[key]
       end
 
+      def request_schema(content)
+        return if content.nil?
+
+        type = REQUEST_SCHEMA_TYPES.find { |item| content.key?(item) }
+        return if type.nil?
+
+        node = valuekey(content[type], 'schema')
+        return if node.nil?
+
+        if node.to_s.include?('#/components/schemas/')
+          schema(node)
+        else
+          schema_new(node, @documentation['definitions'])
+        end
+      end
+
       def schema_new(sche, defi)
+        json_schema(schema_new_raw(sche, defi))
+      end
+
+      def schema_new_raw(sche, defi)
         return sche unless sche
+
         if sche.keys.include?('$ref')
           res = sche.merge('definitions' => { sche['$ref'][14..-1] => defi[sche['$ref'][14..-1]] })
           if defi[sche['$ref'][14..-1]].to_s.include?('$ref')
@@ -66,12 +95,22 @@ module Tomograph
           if response['content'].nil?
             result.push(
               'status' => response_code,
-              'body'=> {},
+              'body' => {},
               'content-type' => nil
             )
           else
             result += responses_by_content_types(response['content'], response_code)
           end
+
+          # API Blueprint allowed a second response with the same status and an
+          # empty body. Fitting treats that pair as an optional schema.
+          if response['x-empty-body']
+            result.push(
+              'status' => response_code,
+              'body' => {},
+              'content-type' => 'application/json'
+            )
+          end
         end
         result
       end
@@ -87,6 +126,12 @@ module Tomograph
       end
 
       def schema(sche)
+        json_schema(schema_raw(sche))
+      end
+
+      def schema_raw(sche)
+        return sche unless sche.is_a?(Hash)
+
         if @documentation['components']
           defi = @documentation['components']['schemas']
         elsif @documentation['definitions']
@@ -122,17 +167,87 @@ module Tomograph
           sche
 
         elsif sche.to_s.include?('$ref')
-          res = sche.merge('definitions' => {})
-          keys = sche.to_s.split('"').find_all { |word| word.include?('definitions') }
-          keys.each do |key|
-            res['definitions'].merge!({ key.split('/')[-1] => defi[key.split('/')[-1]] })
-          end
-          res
+          res = attach_definitions(sche, defi)
+          attach_component_schemas(res)
         else
           sche
         end
       end
 
+      def attach_definitions(sche, defi)
+        keys = sche.to_s.split('"').find_all { |word| word.include?('definitions') }
+        return sche if keys.empty?
+
+        res = sche.merge('definitions' => {})
+        keys.each do |key|
+          name = key.split('/')[-1]
+          res['definitions'].merge!(name => defi[name])
+        end
+        res
+      end
+
+      def attach_component_schemas(sche)
+        schemas = @documentation.dig('components', 'schemas')
+        return sche unless schemas
+
+        copied = {}
+        seen = {}
+        copy_component_schemas(copied, seen, component_ref_names(sche), schemas)
+        return sche if copied.empty?
+
+        previous = (sche['components'] || {})
+        schemas = (previous['schemas'] || {}).merge(copied)
+        sche.merge('components' => previous.merge('schemas' => schemas))
+      end
+
+      def copy_component_schemas(copied, seen, names, schemas)
+        names.each do |name|
+          next if seen[name]
+          next unless schemas[name]
+
+          seen[name] = true
+          copied[name] = schemas[name]
+          copy_component_schemas(copied, seen, component_ref_names(schemas[name]), schemas)
+        end
+      end
+
+      def component_ref_names(schema)
+        schema.to_s.split('"').find_all { |word| word.include?('#/components/schemas/') }
+              .map { |word| word[21..-1] }
+              .uniq
+      end
+
+      # OpenAPI 3 `nullable: true` is not a JSON Schema keyword. Draft-04, which
+      # the tomogram is validated against, allows null only via the type list.
+      def json_schema(node)
+        case node
+        when Hash
+          converted = {}
+          node.each { |key, value| converted[key] = json_schema(value) }
+          nullable_to_type(converted)
+        when Array
+          node.map { |value| json_schema(value) }
+        else
+          node
+        end
+      end
+
+      def nullable_to_type(schema)
+        return schema unless schema.key?('nullable')
+
+        nullable = schema.delete('nullable')
+        return schema unless nullable
+
+        case schema['type']
+        when String
+          schema['type'] = [schema['type'], 'null']
+        when Array
+          schema['type'] = schema['type'].dup
+          schema['type'] << 'null' unless schema['type'].include?('null')
+        end
+        schema
+      end
+
       def search_hash(hash, key)
         return hash[key] if hash.assoc(key)
 

data/lib/tomograph/version.rb

@@ -1,3 +1,3 @@
 module Tomograph
-  VERSION = '3.2.7'.freeze
+  VERSION = '4.0.0'.freeze
 end

data/tomograph.gemspec

@@ -5,8 +5,8 @@ require 'tomograph/version'
 Gem::Specification.new do |spec|
   spec.name           = 'tomograph'
   spec.version        = Tomograph::VERSION
-  spec.authors        = ['d.efimov']
-  spec.email          = ['d.efimov@fun-box.ru']
+  spec.authors        = ['Dmitry Efimov']
+  spec.email          = ['tuwilof@gmail.com']
 
   spec.summary        = 'Convert API Blueprint, Swagger and OpenAPI to Tomogram'
   spec.description    = 'Convert API Blueprint, Swagger and OpenAPI to routes and JSON-Schemas'
@@ -25,5 +25,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec', '~> 3.10', '>= 3.10.0'
   spec.add_development_dependency 'rubocop', '~> 0.81', '>= 0.81.0'
   spec.add_development_dependency 'simplecov', '~> 0.21', '>= 0.21.2'
-  spec.required_ruby_version = '>= 2.4.0'
+  spec.required_ruby_version = '>= 3.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tomograph
 version: !ruby/object:Gem::Version
-  version: 3.2.7
+  version: 4.0.0
 platform: ruby
 authors:
-- d.efimov
-autorequire:
+- Dmitry Efimov
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-12-08 00:00:00.000000000 Z
+date: 2026-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: methadone
@@ -146,7 +146,7 @@ dependencies:
         version: 0.21.2
 description: Convert API Blueprint, Swagger and OpenAPI to routes and JSON-Schemas
 email:
-- d.efimov@fun-box.ru
+- tuwilof@gmail.com
 executables:
 - tomograph
 extensions: []
@@ -172,6 +172,7 @@ files:
 - lib/tomograph/api_blueprint/drafter_4/yaml.rb
 - lib/tomograph/api_blueprint/drafter_4/yaml/action.rb
 - lib/tomograph/api_blueprint/json_schema.rb
+- lib/tomograph/openapi/external_ref_resolver.rb
 - lib/tomograph/openapi/openapi2.rb
 - lib/tomograph/openapi/openapi3.rb
 - lib/tomograph/path.rb
@@ -184,7 +185,7 @@ homepage: https://github.com/tuwilof/tomograph
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -192,7 +193,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.4.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -200,7 +201,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.2.22
-signing_key:
+signing_key: 
 specification_version: 4
 summary: Convert API Blueprint, Swagger and OpenAPI to Tomogram
 test_files: []