swagger23 0.1.0

data/lib/swagger23.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "swagger23/version"
+require_relative "swagger23/error"
+require_relative "swagger23/ref_rewriter"
+require_relative "swagger23/schema_processor"
+require_relative "swagger23/converters/info"
+require_relative "swagger23/converters/servers"
+require_relative "swagger23/converters/paths"
+require_relative "swagger23/converters/components"
+require_relative "swagger23/converters/security"
+require_relative "swagger23/converter"
+
+module Swagger23
+  # Parse a JSON or YAML string into a Ruby Hash.
+  #
+  # Detection strategy: inspect the first non-whitespace byte.
+  #   '{' or '['  →  JSON  (the only two valid JSON document starters)
+  #   anything else  →  YAML
+  #
+  # This avoids trying to JSON-parse a UTF-8 YAML string, which raises
+  # Encoding::InvalidByteSequenceError when the Ruby process is running with
+  # an ASCII locale.
+  #
+  # @param source [String] raw JSON or YAML content
+  # @return [Hash] parsed document
+  # @raise [Swagger23::Error] if the source cannot be parsed as either format
+  def self.parse(source)
+    # Ensure we always work with a UTF-8 string regardless of how the caller
+    # obtained it (File.read without encoding:, STDIN.read, etc.).
+    source = source.dup.force_encoding("UTF-8") unless source.encoding == Encoding::UTF_8
+
+    first = source.lstrip[0]
+
+    if first == "{" || first == "["
+      begin
+        JSON.parse(source)
+      rescue JSON::ParserError => e
+        raise Swagger23::Error, "JSON parse error: #{e.message}"
+      end
+    else
+      require "yaml"
+      begin
+        result = YAML.safe_load(source)
+      rescue Psych::SyntaxError => e
+        raise Swagger23::Error, "Could not parse input as YAML: #{e.message}"
+      end
+
+      if result.nil?
+        raise Swagger23::Error, "Could not parse input: document is empty or null"
+      end
+
+      unless result.is_a?(Hash)
+        raise Swagger23::Error, "Input parsed to #{result.class}, expected a Hash"
+      end
+
+      result
+    end
+  end
+
+  # Convert a Swagger 2.0 Hash to an OpenAPI 3.0 Hash.
+  #
+  # @param swagger [Hash] parsed Swagger 2.0 document
+  # @return [Hash] OpenAPI 3.0 document
+  def self.convert(swagger)
+    Converter.new(swagger).convert
+  end
+
+  # Parse a JSON or YAML string and return the converted OpenAPI 3.0 document
+  # as a pretty-printed JSON string.
+  #
+  # @param source [String] Swagger 2.0 document as JSON or YAML
+  # @return [String] OpenAPI 3.0 document as JSON
+  def self.convert_string(source)
+    JSON.pretty_generate(convert(parse(source)))
+  end
+
+  # Parse a JSON or YAML string and return the converted OpenAPI 3.0 document
+  # as a YAML string.
+  #
+  # @param source [String] Swagger 2.0 document as JSON or YAML
+  # @return [String] OpenAPI 3.0 document as YAML
+  def self.convert_to_yaml(source)
+    require "yaml"
+    YAML.dump(stringify_keys_deep(convert(parse(source))))
+  end
+
+  # @deprecated Use {convert_string} instead (identical behaviour, clearer name).
+  def self.convert_json(source)
+    convert_string(source)
+  end
+
+  # ── Internal helpers ──────────────────────────────────────────────────────
+
+  # YAML.dump can emit symbols as keys if the hash was built with symbol keys.
+  # Our converter always uses string keys (coming from JSON.parse), but we
+  # normalise just in case a caller passes in a symbolised hash.
+  def self.stringify_keys_deep(obj)
+    case obj
+    in Hash
+      obj.each_with_object({}) do |(k, v), h|
+        h[k.to_s] = stringify_keys_deep(v)
+      end
+    in Array
+      obj.map { |item| stringify_keys_deep(item) }
+    else
+      obj
+    end
+  end
+  private_class_method :stringify_keys_deep
+end

data/sig/swagger23.rbs

@@ -0,0 +1,71 @@
+# Type signatures for the swagger23 gem public API.
+# Compatible with Steep, Sorbet (via rbs), and IDEs such as RubyMine / VS Code + ruby-lsp.
+
+module Swagger23
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class InvalidSwaggerError < Error
+  end
+
+  # Parse a JSON or YAML string into a Ruby Hash.
+  def self.parse: (String source) -> Hash[String, untyped]
+
+  # Convert a Swagger 2.0 Hash to an OpenAPI 3.0 Hash.
+  def self.convert: (Hash[String, untyped] swagger) -> Hash[String, untyped]
+
+  # Parse and convert, returning a pretty-printed JSON string.
+  def self.convert_string: (String source) -> String
+
+  # Parse and convert, returning a YAML string.
+  def self.convert_to_yaml: (String source) -> String
+
+  # @deprecated Use convert_string instead.
+  def self.convert_json: (String source) -> String
+
+  class Converter
+    SUPPORTED_SWAGGER_VERSION: String
+    TARGET_OPENAPI_VERSION: String
+
+    def initialize: (Hash[String, untyped] swagger) -> void
+    def convert: () -> Hash[String, untyped]
+  end
+
+  module RefRewriter
+    REF_MAP: Hash[String, String]
+
+    def self.rewrite: (untyped obj) -> untyped
+  end
+
+  module SchemaProcessor
+    def self.process: (untyped obj) -> untyped
+  end
+
+  module Converters
+    module Info
+      def self.convert: (Hash[String, untyped] swagger) -> Hash[String, untyped]
+    end
+
+    module Servers
+      def self.convert: (Hash[String, untyped] swagger) -> Array[Hash[String, untyped]]
+    end
+
+    module Paths
+      HTTP_METHODS: Array[String]
+
+      def self.convert: (Hash[String, untyped] swagger) -> Hash[String, untyped]
+    end
+
+    module Components
+      def self.convert: (Hash[String, untyped] swagger) -> Hash[String, untyped]
+    end
+
+    module Security
+      def self.convert: (Hash[String, untyped] swagger) -> Hash[String, untyped]
+    end
+
+    ParameterConverter: singleton(Paths)
+  end
+end

data/swagger23.gemspec

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "lib/swagger23/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "swagger23"
+  spec.version       = Swagger23::VERSION
+  spec.authors       = ["Maxim Veysgeym"]
+  spec.email         = []
+  spec.summary       = "Convert Swagger 2.0 to OpenAPI 3.0 — Ruby library and CLI"
+  spec.description   = <<~DESC
+    swagger23 converts Swagger 2.0 (OAS 2) API specifications into OpenAPI 3.0.3 (OAS 3)
+    specifications. Accepts JSON or YAML input, produces JSON or YAML output.
+    Works as a Ruby library (Swagger23.convert) or a standalone CLI tool (swagger23).
+    Handles paths, parameters, requestBody, components/schemas, securitySchemes,
+    servers, $ref rewriting, collectionFormat, x-nullable, discriminator, OAuth2 flows,
+    and file uploads. No external runtime dependencies. Safe for large specs.
+  DESC
+  spec.license       = "MIT"
+  spec.homepage      = "https://github.com/Qew7/swagger23"
+
+  spec.metadata = {
+    "homepage_uri"      => spec.homepage,
+    "source_code_uri"   => spec.homepage,
+    "bug_tracker_uri"   => "#{spec.homepage}/issues",
+    "documentation_uri" => "#{spec.homepage}/blob/main/README.md"
+  }
+
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "sig/**/*.rbs",
+    "bin/*",
+    "swagger23.gemspec",
+    "README.md",
+    "LICENSE"
+  ]
+
+  spec.bindir        = "bin"
+  spec.executables   = ["swagger23"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "json",       ">= 2.0"
+
+  spec.add_development_dependency "rspec",     "~> 3.12"
+  spec.add_development_dependency "rake",      "~> 13.0"
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: swagger23
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Maxim Veysgeym
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |
+  swagger23 converts Swagger 2.0 (OAS 2) API specifications into OpenAPI 3.0.3 (OAS 3)
+  specifications. Accepts JSON or YAML input, produces JSON or YAML output.
+  Works as a Ruby library (Swagger23.convert) or a standalone CLI tool (swagger23).
+  Handles paths, parameters, requestBody, components/schemas, securitySchemes,
+  servers, $ref rewriting, collectionFormat, x-nullable, discriminator, OAuth2 flows,
+  and file uploads. No external runtime dependencies. Safe for large specs.
+email: []
+executables:
+- swagger23
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/swagger23
+- lib/swagger23.rb
+- lib/swagger23/converter.rb
+- lib/swagger23/converters/components.rb
+- lib/swagger23/converters/info.rb
+- lib/swagger23/converters/paths.rb
+- lib/swagger23/converters/security.rb
+- lib/swagger23/converters/servers.rb
+- lib/swagger23/error.rb
+- lib/swagger23/ref_rewriter.rb
+- lib/swagger23/schema_processor.rb
+- lib/swagger23/version.rb
+- sig/swagger23.rbs
+- swagger23.gemspec
+homepage: https://github.com/Qew7/swagger23
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Qew7/swagger23
+  source_code_uri: https://github.com/Qew7/swagger23
+  bug_tracker_uri: https://github.com/Qew7/swagger23/issues
+  documentation_uri: https://github.com/Qew7/swagger23/blob/main/README.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Convert Swagger 2.0 to OpenAPI 3.0 — Ruby library and CLI
+test_files: []