swagger23 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 16a875f37fe15619525cdfe4ac7ce4f4c942f15113423221d7a323fe9671792e
+  data.tar.gz: f3de37ab1a4f608db7a97d3589d0883de89763afa8e6d4a24eb43fffbb6903bd
+SHA512:
+  metadata.gz: 1f452044813adb1fed314ca38303aacf92f0776afe11c253e478033edfcb56645439ad7f632a56b81b73f21bb5c1cc95368a119ddb55d06a16dfc70113db667f
+  data.tar.gz: a063e8949e75e1361d47416723d3088eea1d5e61ffafeece2fd811b5df75dea1958dfa83227be423ebafacf2d637c8cb9cf1bf29fc8d4a72ceb27b63a082564e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maxim Veysgeym
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,125 @@
+# swagger23
+
+[![Gem Version](https://badge.fury.io/rb/swagger23.svg)](https://rubygems.org/gems/swagger23)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+A Ruby gem that converts [Swagger 2.0](https://swagger.io/specification/v2/) API specifications into [OpenAPI 3.0.3](https://spec.openapis.org/oas/v3.0.3) specifications.
+
+Accepts **JSON or YAML** input, produces **JSON or YAML** output. Works as a Ruby library or a standalone CLI tool.
+
+---
+
+## Requirements
+
+- Ruby **≥ 3.2**
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "swagger23"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install globally:
+
+```bash
+gem install swagger23
+```
+
+---
+
+## Usage
+
+### CLI
+
+```
+swagger23 [INPUT [OUTPUT]]
+```
+
+| Argument | Description |
+|---|---|
+| `INPUT` | Path to a Swagger 2.0 file (`.json`, `.yaml`, or `.yml`). Reads from **stdin** if omitted. |
+| `OUTPUT` | Path to write the OpenAPI 3.0 result. Format is determined by the file extension: `.yaml` / `.yml` → YAML, anything else → JSON. Writes JSON to **stdout** if omitted. |
+
+**Options:**
+
+```
+-v, --version   Print the gem version and exit.
+-h, --help      Print this help message and exit.
+```
+
+**Examples:**
+
+```bash
+swagger23 petstore.json openapi.json
+swagger23 petstore.yaml openapi.yaml
+swagger23 petstore.yaml openapi.json
+swagger23 petstore.json openapi.yaml
+
+# Print to stdout
+swagger23 petstore.json
+
+# Pipe from stdin
+cat petstore.yaml | swagger23
+cat petstore.json | swagger23 > openapi.json
+```
+
+### Ruby library
+
+```ruby
+require "swagger23"
+
+# Hash → Hash
+swagger_hash = JSON.parse(File.read("petstore.json"))
+openapi_hash = Swagger23.convert(swagger_hash)
+
+# String (JSON or YAML) → JSON string
+json_string = Swagger23.convert_string(File.read("swagger.yaml", encoding: "utf-8"))
+
+# String (JSON or YAML) → YAML string
+yaml_string = Swagger23.convert_to_yaml(File.read("swagger.json", encoding: "utf-8"))
+
+# Parse only
+hash = Swagger23.parse(source)
+```
+
+---
+
+## Running tests
+
+```bash
+bundle exec rspec
+```
+
+---
+
+## Contributing
+
+1. Fork [github.com/Qew7/swagger23](https://github.com/Qew7/swagger23).
+2. Create a feature branch: `git checkout -b my-feature`.
+3. Add tests for your change.
+4. Make sure the full suite passes: `bundle exec rspec`.
+5. Submit a pull request.
+
+Bug reports and feature requests are welcome on the [issue tracker](https://github.com/Qew7/swagger23/issues).
+
+---
+
+## Author
+
+[Maxim Veysgeym](https://github.com/Qew7) — Ruby enthusiast, Moscow.
+
+---
+
+## License
+
+Released under the [MIT License](LICENSE) © 2026 Maxim Veysgeym.

data/bin/swagger23

@@ -0,0 +1,113 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# CLI for swagger23 – converts a Swagger 2.0 file to OpenAPI 3.0.
+#
+# Usage:
+#   swagger23 input.json [output.json]
+#   swagger23 input.yaml [output.yaml]
+#   swagger23 input.yaml output.json   # cross-format
+#   swagger23 input.json               # writes to STDOUT (JSON)
+#   cat input.yaml | swagger23         # reads from STDIN, writes to STDOUT (JSON)
+#   swagger23 --version
+#   swagger23 --help
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "swagger23"
+require "json"
+
+def usage
+  <<~USAGE
+    Usage:
+      swagger23 [INPUT [OUTPUT]]
+
+    Arguments:
+      INPUT   Path to Swagger 2.0 file (.json or .yaml/.yml).
+              Reads from STDIN if omitted.
+      OUTPUT  Path to write OpenAPI 3.0 result.
+              Format is determined by the file extension:
+                .yaml / .yml  →  YAML output
+                anything else →  JSON output  (default)
+              Writes JSON to STDOUT if omitted.
+
+    Options:
+      -v, --version   Print the gem version and exit.
+      -h, --help      Print this help message and exit.
+
+    Examples:
+      swagger23 petstore.json openapi.json
+      swagger23 petstore.yaml openapi.yaml
+      swagger23 petstore.yaml openapi.json
+      swagger23 petstore.json
+      cat petstore.yaml | swagger23
+  USAGE
+end
+
+# ── Argument parsing ──────────────────────────────────────────────────────────
+
+args = ARGV.dup
+
+if args.include?("--help") || args.include?("-h")
+  puts usage
+  exit 0
+end
+
+if args.include?("--version") || args.include?("-v")
+  puts Swagger23::VERSION
+  exit 0
+end
+
+input_path  = args.shift
+output_path = args.shift
+
+# ── Read input ────────────────────────────────────────────────────────────────
+
+begin
+  raw = input_path ? File.read(input_path, encoding: "utf-8") : $stdin.read
+rescue Errno::ENOENT => e
+  warn "swagger23: #{e.message}"
+  exit 1
+end
+
+# ── Parse input (JSON or YAML, auto-detected) ─────────────────────────────────
+
+begin
+  swagger = Swagger23.parse(raw)
+rescue Swagger23::Error => e
+  warn "swagger23: #{e.message}"
+  exit 1
+end
+
+# ── Convert ───────────────────────────────────────────────────────────────────
+
+begin
+  openapi = Swagger23.convert(swagger)
+rescue Swagger23::InvalidSwaggerError => e
+  warn "swagger23: #{e.message}"
+  exit 2
+rescue => e
+  warn "swagger23: unexpected error: #{e.class}: #{e.message}"
+  warn e.backtrace.first(5).join("\n")
+  exit 3
+end
+
+# ── Serialise to output format ────────────────────────────────────────────────
+
+yaml_output = output_path && output_path.match?(/\.ya?ml\z/i)
+
+if yaml_output
+  require "yaml"
+  output = YAML.dump(openapi)
+else
+  output = JSON.pretty_generate(openapi)
+end
+
+# ── Write output ──────────────────────────────────────────────────────────────
+
+if output_path
+  File.write(output_path, output)
+  format = yaml_output ? "YAML" : "JSON"
+  warn "swagger23: written #{format} to #{output_path}"
+else
+  puts output
+end

data/lib/swagger23/converter.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Swagger23
+  # Orchestrates the full Swagger 2.0 → OpenAPI 3.0 conversion.
+  #
+  # Usage:
+  #   swagger_hash = JSON.parse(File.read("petstore.json"))
+  #   openapi_hash = Swagger23::Converter.new(swagger_hash).convert
+  class Converter
+    SUPPORTED_SWAGGER_VERSION = "2.0"
+    TARGET_OPENAPI_VERSION    = "3.0.3"
+
+    # @param swagger [Hash] parsed Swagger 2.0 document
+    def initialize(swagger)
+      @swagger = swagger
+    end
+
+    # @return [Hash] OpenAPI 3.0 document
+    def convert
+      validate!
+
+      result = {}
+
+      result["openapi"] = TARGET_OPENAPI_VERSION
+      result["info"]    = Converters::Info.convert(@swagger)
+      result["servers"] = Converters::Servers.convert(@swagger)
+
+      # Tags (identical structure between 2.0 and 3.0)
+      result["tags"] = @swagger["tags"] if @swagger.key?("tags")
+
+      # External docs (identical)
+      result["externalDocs"] = @swagger["externalDocs"] if @swagger.key?("externalDocs")
+
+      # Paths
+      result["paths"] = Converters::Paths.convert(@swagger)
+
+      # Components
+      components = Converters::Components.convert(@swagger)
+      security_schemes = Converters::Security.convert(@swagger)
+      components["securitySchemes"] = security_schemes unless security_schemes.empty?
+
+      result["components"] = components unless components.empty?
+
+      # Top-level security requirements (identical structure)
+      result["security"] = @swagger["security"] if @swagger.key?("security")
+
+      # Top-level extensions
+      @swagger.each do |key, value|
+        result[key] = value if key.start_with?("x-")
+      end
+
+      # Pass 1: rewrite all $ref values (Swagger 2.0 paths → OpenAPI 3.0 paths)
+      rewritten = RefRewriter.rewrite(result)
+
+      # Pass 2: schema-level semantic transformations
+      #   x-nullable → nullable, discriminator string → object, type arrays → nullable
+      SchemaProcessor.process(rewritten)
+    end
+
+    private
+
+    def validate!
+      version = @swagger["swagger"]
+      return if version.to_s == SUPPORTED_SWAGGER_VERSION
+
+      raise InvalidSwaggerError,
+            "Expected swagger version '#{SUPPORTED_SWAGGER_VERSION}', " \
+            "got '#{version}'. Only Swagger 2.0 documents are supported."
+    end
+  end
+end

data/lib/swagger23/converters/components.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Swagger23
+  module Converters
+    # Converts Swagger 2.0 top-level reusable objects into OpenAPI 3.0
+    # `components` section.
+    #
+    # Mapping:
+    #   definitions         → components/schemas
+    #   parameters          → components/parameters
+    #   responses           → components/responses
+    #   securityDefinitions → components/securitySchemes  (see Security converter)
+    module Components
+      def self.convert(swagger)
+        components = {}
+
+        if (definitions = swagger["definitions"])
+          components["schemas"] = definitions
+        end
+
+        if (parameters = swagger["parameters"])
+          converted_params = {}
+          parameters.each do |name, param|
+            converted_params[name] = Paths.convert_parameter(param)
+          end
+          components["parameters"] = converted_params
+        end
+
+        if (responses = swagger["responses"])
+          converted_responses = {}
+          responses.each do |name, resp|
+            converted_responses[name] = convert_response(resp, swagger)
+          end
+          components["responses"] = converted_responses
+        end
+
+        components
+      end
+
+      # Convert a single Swagger 2.0 response object to OpenAPI 3.0 format.
+      def self.convert_response(resp, swagger)
+        result = {}
+        result["description"] = resp["description"] if resp["description"]
+
+        if (schema = resp["schema"])
+          produces = swagger["produces"] || ["application/json"]
+          content  = {}
+          produces.each do |mime|
+            content[mime] = { "schema" => schema }
+          end
+          result["content"] = content
+        end
+
+        # 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 = resp["headers"])
+          converted_headers = {}
+          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_headers[name] = h
+          end
+          result["headers"] = converted_headers
+        end
+
+        # pass through extensions
+        resp.each do |key, value|
+          result[key] = value if key.start_with?("x-")
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/swagger23/converters/info.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Swagger23
+  module Converters
+    # Converts the top-level `info` object.
+    # The structure is identical between Swagger 2.0 and OpenAPI 3.0,
+    # so this is essentially a deep-copy with no structural changes.
+    module Info
+      def self.convert(swagger)
+        info = swagger["info"] || {}
+        # Pass through all known and extension fields as-is
+        info.dup
+      end
+    end
+  end
+end