swagger23 0.1.0

data/lib/swagger23/converters/paths.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module Swagger23
+  module Converters
+    # Converts Swagger 2.0 `paths` to OpenAPI 3.0 `paths`.
+    #
+    # Key transformations per operation:
+    #   - `in: body` parameter          → requestBody
+    #   - `in: formData` parameters     → requestBody (form-encoded or multipart)
+    #   - `consumes` / `produces`       → content-type keys in requestBody / responses
+    #   - response `schema`             → response.content[mime].schema
+    #   - response headers              → response.headers (simplified)
+    #   - all other parameters unchanged (path, query, header, cookie)
+    module Paths
+      HTTP_METHODS = %w[get put post delete options head patch trace].freeze
+
+      # @param swagger [Hash] the full Swagger 2.0 document (needed for global consumes/produces)
+      def self.convert(swagger)
+        paths = swagger["paths"] || {}
+        global_consumes = Array(swagger["consumes"])
+        global_produces = Array(swagger["produces"])
+
+        converted = {}
+        paths.each do |path, path_item|
+          converted[path] = convert_path_item(path_item, global_consumes, global_produces)
+        end
+        converted
+      end
+
+      # -------------------------------------------------------------------------
+      # Path item
+      # -------------------------------------------------------------------------
+
+      def self.convert_path_item(path_item, global_consumes, global_produces)
+        # Swagger 2.0 allows a $ref at path-item level (e.g. to share path items).
+        # Pass it through; RefRewriter will rewrite the ref if it matches a known prefix.
+        return path_item.dup if path_item.key?("$ref")
+
+        result = {}
+
+        # Path-level parameters (non-operation)
+        if (params = path_item["parameters"])
+          result["parameters"] = params.map { |p| convert_parameter(p) }
+        end
+
+        # Copy path-level extensions
+        path_item.each do |key, value|
+          result[key] = value if key.start_with?("x-")
+        end
+
+        HTTP_METHODS.each do |method|
+          next unless path_item.key?(method)
+
+          result[method] = convert_operation(
+            path_item[method],
+            global_consumes,
+            global_produces
+          )
+        end
+
+        result
+      end
+
+      # -------------------------------------------------------------------------
+      # Operation
+      # -------------------------------------------------------------------------
+
+      def self.convert_operation(op, global_consumes, global_produces)
+        result = {}
+
+        # Passthrough scalar fields
+        %w[summary description operationId deprecated tags externalDocs].each do |field|
+          result[field] = op[field] if op.key?(field)
+        end
+
+        # Security
+        result["security"] = op["security"] if op.key?("security")
+
+        # Extensions
+        op.each { |k, v| result[k] = v if k.start_with?("x-") }
+
+        # Effective consumes / produces for this operation
+        op_consumes = Array(op["consumes"]).then { |a| a.empty? ? global_consumes : a }
+        op_produces = Array(op["produces"]).then { |a| a.empty? ? global_produces : a }
+
+        # Default mime types when none specified
+        op_consumes = ["application/json"] if op_consumes.empty?
+        op_produces = ["application/json"] if op_produces.empty?
+
+        # Split parameters
+        all_params   = Array(op["parameters"])
+        body_param   = all_params.find { |p| p["in"] == "body" }
+        form_params  = all_params.select { |p| p["in"] == "formData" }
+        other_params = all_params.reject { |p| %w[body formData].include?(p["in"]) }
+
+        # Regular parameters (path / query / header / cookie)
+        unless other_params.empty?
+          result["parameters"] = other_params.map { |p| convert_parameter(p) }
+        end
+
+        # requestBody from body parameter
+        if body_param
+          result["requestBody"] = build_request_body_from_body_param(body_param, op_consumes)
+        elsif !form_params.empty?
+          result["requestBody"] = build_request_body_from_form_params(form_params, op_consumes)
+        end
+
+        # responses
+        if (responses = op["responses"])
+          result["responses"] = convert_responses(responses, op_produces)
+        end
+
+        # callbacks – not present in Swagger 2.0, skip
+        result
+      end
+
+      # -------------------------------------------------------------------------
+      # Parameters
+      # -------------------------------------------------------------------------
+
+      # Convert a single non-body/formData parameter.
+      def self.convert_parameter(param)
+        return param if param.key?("$ref")
+
+        result = {}
+        %w[name in description required deprecated allowEmptyValue].each do |field|
+          result[field] = param[field] if param.key?(field)
+        end
+
+        # OAS 3.0 §4.8.12.1: path parameters MUST have required: true.
+        # Swagger 2.0 technically requires it too, but many real specs omit it.
+        result["required"] = true if result["in"] == "path"
+
+        # `collectionFormat` → `style` + `explode`
+        if (schema = build_param_schema(param))
+          result["schema"] = schema
+        end
+
+        # Extensions
+        param.each { |k, v| result[k] = v if k.start_with?("x-") }
+
+        result
+      end
+
+      # Build the schema for a parameter from its inline type/format/etc.
+      def self.build_param_schema(param)
+        # If there's already a nested schema object use it
+        return param["schema"] if param.key?("schema")
+
+        schema = {}
+        %w[type format default enum minimum maximum minLength maxLength
+           pattern items uniqueItems collectionFormat].each do |field|
+          schema[field] = param[field] if param.key?(field)
+        end
+
+        # collectionFormat → style
+        if (collection_format = schema.delete("collectionFormat"))
+          case collection_format
+          when "csv"   then schema["style"] = "form";   schema["explode"] = false
+          when "ssv"   then schema["style"] = "spaceDelimited"
+          when "tsv"   then schema["style"] = "tabDelimited"
+          when "pipes" then schema["style"] = "pipeDelimited"
+          when "multi" then schema["style"] = "form";   schema["explode"] = true
+          end
+        end
+
+        schema.empty? ? nil : schema
+      end
+
+      # -------------------------------------------------------------------------
+      # requestBody helpers
+      # -------------------------------------------------------------------------
+
+      def self.build_request_body_from_body_param(body_param, consumes)
+        schema  = body_param["schema"] || {}
+        content = {}
+
+        consumes.each do |mime|
+          content[mime] = { "schema" => schema }
+        end
+
+        result = { "content" => content }
+        result["description"] = body_param["description"] if body_param["description"]
+        result["required"]    = body_param["required"]    if body_param.key?("required")
+        result
+      end
+
+      def self.build_request_body_from_form_params(form_params, consumes)
+        properties = {}
+        required   = []
+
+        form_params.each do |param|
+          name   = param["name"]
+          schema = build_param_schema(param) || {}
+
+          # file upload → binary string
+          if param["type"] == "file"
+            schema = { "type" => "string", "format" => "binary" }
+          end
+
+          schema["description"] = param["description"] if param["description"]
+          properties[name] = schema
+          required << name if param["required"]
+        end
+
+        form_schema = { "type" => "object", "properties" => properties }
+        form_schema["required"] = required unless required.empty?
+
+        # Decide content-type: multipart/form-data if any file uploads
+        has_file = form_params.any? { |p| p["type"] == "file" }
+        mime     = has_file ? "multipart/form-data" : "application/x-www-form-urlencoded"
+
+        # If the operation already declares an explicit form mime, honour it
+        explicit = consumes.find { |c| c =~ /multipart|form-urlencoded/ }
+        mime     = explicit || mime
+
+        { "content" => { mime => { "schema" => form_schema } } }
+      end
+
+      # -------------------------------------------------------------------------
+      # Responses
+      # -------------------------------------------------------------------------
+
+      def self.convert_responses(responses, produces)
+        result = {}
+        responses.each do |status, response|
+          result[status.to_s] = convert_response(response, produces)
+        end
+        result
+      end
+
+      def self.convert_response(response, produces)
+        return response if response.key?("$ref")
+
+        result = {}
+        result["description"] = response["description"] || ""
+
+        # schema → content
+        if (schema = response["schema"])
+          content = {}
+          produces.each do |mime|
+            content[mime] = { "schema" => schema }
+          end
+          result["content"] = content
+        end
+
+        # headers
+        # OAS 3.0 Header Object: description stays at the top level; type/format go
+        # inside a nested `schema` object (Header Object mirrors Parameter Object).
+        if (headers = response["headers"])
+          converted = {}
+          headers.each do |name, header|
+            h = {}
+            h["description"] = header["description"] if header.key?("description")
+            schema = {}
+            %w[type format].each { |f| schema[f] = header[f] if header.key?(f) }
+            h["schema"] = schema unless schema.empty?
+            header.each { |k, v| h[k] = v if k.start_with?("x-") }
+            converted[name] = h
+          end
+          result["headers"] = converted
+        end
+
+        # extensions
+        response.each { |k, v| result[k] = v if k.start_with?("x-") }
+
+        result
+      end
+    end
+
+    # Alias used by Components converter for shared parameter conversion
+    ParameterConverter = Paths
+  end
+end

data/lib/swagger23/converters/security.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Swagger23
+  module Converters
+    # Converts Swagger 2.0 `securityDefinitions` to OpenAPI 3.0
+    # `components/securitySchemes`.
+    #
+    # Swagger 2.0 types and their OpenAPI 3.0 equivalents:
+    #
+    #   basic           → http / scheme: basic
+    #   apiKey          → apiKey (identical structure)
+    #   oauth2 implicit → oauth2 / flows.implicit
+    #   oauth2 password → oauth2 / flows.password
+    #   oauth2 application → oauth2 / flows.clientCredentials
+    #   oauth2 accessCode  → oauth2 / flows.authorizationCode
+    module Security
+      def self.convert(swagger)
+        defs = swagger["securityDefinitions"]
+        return {} unless defs
+
+        schemes = {}
+        defs.each do |name, definition|
+          schemes[name] = convert_scheme(definition)
+        end
+        schemes
+      end
+
+      def self.convert_scheme(defn)
+        type = defn["type"]
+
+        case type
+        when "basic"
+          result = { "type" => "http", "scheme" => "basic" }
+          result["description"] = defn["description"] if defn["description"]
+          add_extensions(result, defn)
+          result
+
+        when "apiKey"
+          result = {
+            "type" => "apiKey",
+            "name" => defn["name"],
+            "in"   => defn["in"]
+          }
+          result["description"] = defn["description"] if defn["description"]
+          add_extensions(result, defn)
+          result
+
+        when "oauth2"
+          convert_oauth2(defn)
+
+        else
+          # Unknown type – pass through as-is with extensions
+          result = defn.dup
+          result
+        end
+      end
+
+      def self.convert_oauth2(defn)
+        flow_name = defn["flow"]
+        result = { "type" => "oauth2" }
+        result["description"] = defn["description"] if defn["description"]
+
+        scopes         = defn["scopes"] || {}
+        auth_url       = defn["authorizationUrl"]
+        token_url      = defn["tokenUrl"]
+
+        flow = {}
+        flow["scopes"] = scopes
+
+        case flow_name
+        when "implicit"
+          flow["authorizationUrl"] = auth_url
+          result["flows"] = { "implicit" => flow }
+        when "password"
+          flow["tokenUrl"] = token_url
+          result["flows"] = { "password" => flow }
+        when "application"
+          flow["tokenUrl"] = token_url
+          result["flows"] = { "clientCredentials" => flow }
+        when "accessCode"
+          flow["authorizationUrl"] = auth_url
+          flow["tokenUrl"]         = token_url
+          result["flows"] = { "authorizationCode" => flow }
+        else
+          result["flows"] = {}
+        end
+
+        add_extensions(result, defn)
+        result
+      end
+
+      def self.add_extensions(result, defn)
+        defn.each do |key, value|
+          result[key] = value if key.start_with?("x-")
+        end
+      end
+    end
+  end
+end

data/lib/swagger23/converters/servers.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Swagger23
+  module Converters
+    # Converts Swagger 2.0 `host` + `basePath` + `schemes` into an OpenAPI 3.0
+    # `servers` array.
+    #
+    # Swagger 2.0 fields used:
+    #   host      – e.g. "api.example.com" or "api.example.com:8080"
+    #   basePath  – e.g. "/v2"
+    #   schemes   – e.g. ["https", "http"]
+    #
+    # OpenAPI 3.0 result:
+    #   servers:
+    #     - url: https://api.example.com/v2
+    #     - url: http://api.example.com/v2
+    module Servers
+      DEFAULT_HOST     = "localhost"
+      DEFAULT_BASEPATH = "/"
+
+      def self.convert(swagger)
+        host      = swagger["host"]     || DEFAULT_HOST
+        base_path = swagger["basePath"] || DEFAULT_BASEPATH
+        schemes   = Array(swagger["schemes"])
+
+        base_path = "/#{base_path}" unless base_path.start_with?("/")
+
+        # When no schemes are provided, default to https and use the actual host.
+        effective_schemes = schemes.empty? ? ["https"] : schemes
+
+        effective_schemes.map do |scheme|
+          { "url" => "#{scheme}://#{host}#{base_path}" }
+        end
+      end
+    end
+  end
+end

data/lib/swagger23/error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Swagger23
+  class Error < StandardError; end
+
+  # Raised when the input document is not a valid Swagger 2.0 document.
+  class InvalidSwaggerError < Error; end
+end

data/lib/swagger23/ref_rewriter.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Swagger23
+  # Walks any JSON-like structure and rewrites all $ref values so that internal
+  # Swagger 2.0 references are mapped to their OpenAPI 3.0 equivalents.
+  #
+  # Rewrite rules:
+  #   #/definitions/Foo        → #/components/schemas/Foo
+  #   #/parameters/Foo         → #/components/parameters/Foo
+  #   #/responses/Foo          → #/components/responses/Foo
+  #   #/securityDefinitions/X  → #/components/securitySchemes/X
+  #
+  # Implementation note:
+  #   Uses an iterative BFS on a JSON deep-clone rather than recursion so that
+  #   very large or deeply nested specifications never risk a SystemStackError.
+  #   The JSON round-trip (C extension) is the fastest way to deep-clone an
+  #   arbitrary JSON-compatible Ruby object and ensures no shared references
+  #   with the original swagger document remain.
+  module RefRewriter
+    REF_MAP = {
+      "#/definitions/"         => "#/components/schemas/",
+      "#/parameters/"          => "#/components/parameters/",
+      "#/responses/"           => "#/components/responses/",
+      "#/securityDefinitions/" => "#/components/securitySchemes/"
+    }.freeze
+
+    # @param obj [Hash, Array, Object] JSON-compatible Ruby object
+    # @return a deep copy of obj with all $ref strings rewritten
+    def self.rewrite(obj)
+      # Deep-clone via JSON round-trip: fast (C ext), handles shared refs,
+      # does not mutate the original document.
+      # max_nesting: false disables JSON's default 100-level depth guard —
+      # real Swagger specs (e.g. Kubernetes) can have deeply nested allOf/anyOf
+      # compositions that exceed that limit.
+      clone = JSON.parse(JSON.generate(obj, max_nesting: false), max_nesting: false)
+
+      # Iterative BFS – O(n) in node count, O(max_width) in memory.
+      # Mutates the clone in-place; no recursion, no stack pressure.
+      queue = [clone]
+      until queue.empty?
+        current = queue.shift
+
+        case current
+        in Hash
+          current.each_pair do |key, value|
+            case [key, value]
+            in ["$ref", String => ref]
+              current[key] = rewrite_ref(ref)
+            in [_, Hash | Array => nested]
+              queue << nested
+            else
+              # primitive value — nothing to traverse
+            end
+          end
+        in Array
+          current.each { |item| queue << item if item in Hash | Array }
+        else
+          # scalar root (e.g. rewrite(42)) — nothing to do
+        end
+      end
+
+      clone
+    end
+
+    def self.rewrite_ref(ref)
+      REF_MAP.each do |from, to|
+        return ref.sub(from, to) if ref.start_with?(from)
+      end
+      ref
+    end
+  end
+end

data/lib/swagger23/schema_processor.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Swagger23
+  # Performs schema-level semantic transformations that bridge Swagger 2.0 and
+  # OpenAPI 3.0 type systems.  Operates on the already-converted, already
+  # $ref-rewritten document (i.e. called after RefRewriter).
+  #
+  # Transformations applied to every Hash node in the document:
+  #
+  #   1. x-nullable: true  →  nullable: true   (x-nullable key removed)
+  #      Common in Java/Spring Boot codegen, AWS API Gateway exports, and any
+  #      tool targeting Swagger 2.0 that needed to express nullability.
+  #
+  #   2. discriminator: "PropName"  →  discriminator: {propertyName: "PropName"}
+  #      Swagger 2.0 uses a bare string; OAS 3.0 uses an object.
+  #
+  #   3. type: ["SomeType", "null"]  →  type: "SomeType", nullable: true
+  #      Several tools (e.g. swagger-codegen from JSON Schema draft 4 sources)
+  #      emit an array of types to express nullability.  OAS 3.0 uses nullable.
+  #
+  # Uses an iterative BFS (same pattern as RefRewriter) to avoid stack overflow
+  # on deeply nested documents.
+  module SchemaProcessor
+    # @param obj [Hash, Array, Object] the already-converted OpenAPI 3.0 tree
+    # @return obj mutated in-place
+    def self.process(obj)
+      queue = [obj]
+      until queue.empty?
+        current = queue.shift
+
+        case current
+        in Hash
+          transform!(current)
+          current.each_value { |v| queue << v if v in Hash | Array }
+        in Array
+          current.each { |item| queue << item if item in Hash | Array }
+        else
+          # scalar or nil — nothing to transform
+        end
+      end
+
+      obj
+    end
+
+    # ---------------------------------------------------------------------------
+    # Per-node transformations
+    # ---------------------------------------------------------------------------
+
+    def self.transform!(h)
+      nullable_from_x_nullable!(h)
+      coerce_discriminator!(h)
+      unwrap_type_array!(h)
+    end
+
+    # x-nullable: true  →  nullable: true
+    # If nullable is already explicitly set we respect it and still remove x-nullable.
+    def self.nullable_from_x_nullable!(h)
+      return unless h.key?("x-nullable")
+
+      h["nullable"] = h["x-nullable"] unless h.key?("nullable")
+      h.delete("x-nullable")
+    end
+
+    # discriminator: "PropName"  →  discriminator: {propertyName: "PropName"}
+    # If discriminator is already an object (already-converted or OAS 3 input), leave it.
+    def self.coerce_discriminator!(h)
+      return unless h.key?("discriminator") && h["discriminator"].is_a?(String)
+
+      h["discriminator"] = { "propertyName" => h["discriminator"] }
+    end
+
+    # type: ["T", "null"]  →  type: "T", nullable: true
+    # type: ["T"]          →  type: "T"           (single-element array)
+    # type: ["A", "B"]     →  kept as-is          (union of non-null types — no standard mapping)
+    def self.unwrap_type_array!(h)
+      return unless h.key?("type") && h["type"].is_a?(Array)
+
+      types    = h["type"]
+      non_null = types.reject { |t| t == "null" }
+      has_null = non_null.size < types.size
+
+      if non_null.size == 1
+        h["type"]     = non_null.first
+        h["nullable"] = true if has_null
+      elsif non_null.empty?
+        # type: ["null"] — technically invalid but handle gracefully
+        h.delete("type")
+        h["nullable"] = true
+      end
+      # else: multiple non-null types — leave array intact; let the validator surface it
+    end
+  end
+end

data/lib/swagger23/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Swagger23
+  VERSION = "0.1.0"
+end