### Install swagger23 Gem

Source: https://github.com/qew7/swagger23/blob/master/README.md

Instructions for installing the swagger23 gem using Bundler or as a standalone gem. Ensures the gem is available for use in your Ruby project.

```ruby
gem "swagger23"
```

```bash
bundle install
```

```bash
gem install swagger23
```

--------------------------------

### CLI: Display Version and Help with Swagger23

Source: https://context7.com/qew7/swagger23/llms.txt

Commands to display the installed Swagger23 gem version and its help message, providing information on usage and options.

```bash
# Print gem version
swagger23 --version
# Output: 0.1.0

# Print help message
swagger23 --help
# Output:
# 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.
```

--------------------------------

### Generate OpenAPI 3.0 Server URLs from Swagger 2.0 Host, BasePath, and Schemes (Ruby)

Source: https://context7.com/qew7/swagger23/llms.txt

This code example illustrates how the Swagger23 converter combines Swagger 2.0 'host', 'basePath', and 'schemes' to generate the OpenAPI 3.0 'servers' array. It demonstrates the creation of a list of server objects, each with a 'url' property.

```ruby
require "swagger23"
require "json"

swagger_doc = {
  "swagger" => "2.0",
  "info" => { "title" => "API", "version" => "1.0" },
  "host" => "api.example.com",
  "basePath" => "/v2",
  "schemes" => ["https", "http"],
  "paths" => {}
}

openapi = Swagger23.convert(swagger_doc)

puts JSON.pretty_generate(openapi["servers"])
# Output:
# [
#   { "url": "https://api.example.com/v2" },
#   { "url": "http://api.example.com/v2" }
# ]
```

--------------------------------

### CLI: Standard Input/Output Conversion with Swagger23

Source: https://context7.com/qew7/swagger23/llms.txt

Shows how to use Swagger23 with standard input and output for pipeline integration. This includes piping files to the tool and redirecting output.

```bash
# Print JSON to stdout
swagger23 petstore.json

# Pipe from stdin (auto-detects JSON or YAML)
cat petstore.yaml | swagger23

# Pipe with output redirection
cat petstore.json | swagger23 > openapi.json

# Chain with other tools
curl -s https://api.example.com/swagger.json | swagger23 | jq '.paths'
```

--------------------------------

### CLI Usage - Options

Source: https://context7.com/qew7/swagger23/llms.txt

Display version information and help documentation for the Swagger23 CLI.

```APIDOC
## CLI Usage - Options

Display version information and help documentation.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Query Parameters
- **--version** - (flag) - Print gem version.
- **--help** - (flag) - Print help message.

### Request Example
```bash
# Print gem version
swagger23 --version

# Print help message
swagger23 --help
```

### Response
#### Success Response (stdout)
- Displays the gem version or a help message detailing usage and options.

#### Response Example
```
# Example for --version
0.1.0

# Example for --help
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.
```
```

--------------------------------

### CLI Usage - Standard Input/Output

Source: https://context7.com/qew7/swagger23/llms.txt

Utilize stdin and stdout for pipeline integration and scripting workflows with the Swagger23 CLI.

```APIDOC
## CLI Usage - Standard Input/Output

Use stdin/stdout for pipeline integration and scripting workflows.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Path Parameters
- **INPUT** (string) - Optional - Path to Swagger 2.0 file (.json or .yaml/.yml). Reads from STDIN if omitted.
- **OUTPUT** (string) - Optional - Path to write OpenAPI 3.0 result. Writes JSON to STDOUT if omitted.

### Request Example
```bash
# Print JSON to stdout
swagger23 petstore.json

# Pipe from stdin (auto-detects JSON or YAML)
cat petstore.yaml | swagger23

# Pipe with output redirection
cat petstore.json | swagger23 > openapi.json

# Chain with other tools
curl -s https://api.example.com/swagger.json | swagger23 | jq '.paths'
```

### Response
#### Success Response (stdout)
- The converted OpenAPI 3.0 specification is printed to standard output.

#### Response Example
```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Swagger Petstore",
    "version": "1.0.0"
  },
  "paths": {
    "/pets": {
      "get": {
        "summary": "List all pets",
        "responses": {
          "200": {
            "description": "A list of pets."
          }
        }
      }
    }
  }
}
```
```

--------------------------------

### CLI Usage for Swagger to OpenAPI Conversion

Source: https://github.com/qew7/swagger23/blob/master/README.md

Demonstrates how to use the swagger23 gem from the command line to convert Swagger 2.0 files to OpenAPI 3.0.3. It covers input/output file specification, stdin/stdout redirection, and option flags.

```bash
swagger23 [INPUT [OUTPUT]]
```

```bash
swagger23 petstore.json openapi.json
```

```bash
swagger23 petstore.yaml openapi.yaml
```

```bash
swagger23 petstore.yaml openapi.json
```

```bash
swagger23 petstore.json openapi.yaml
```

```bash
# Print to stdout
swagger23 petstore.json
```

```bash
# Pipe from stdin
cat petstore.yaml | swagger23
```

```bash
cat petstore.json | swagger23 > openapi.json
```

```bash
swagger23 -v
```

```bash
swagger23 -h
```

--------------------------------

### Run Tests for swagger23 Gem

Source: https://github.com/qew7/swagger23/blob/master/README.md

Command to execute the test suite for the swagger23 gem using RSpec. This is used to verify the gem's functionality and ensure changes haven't introduced regressions.

```bash
bundle exec rspec
```

--------------------------------

### CLI Usage - Basic File Conversion

Source: https://context7.com/qew7/swagger23/llms.txt

Convert Swagger 2.0 files to OpenAPI 3.0 using the CLI. The tool automatically detects input and output formats based on file extensions.

```APIDOC
## CLI Usage - Basic File Conversion

Convert a Swagger 2.0 file to OpenAPI 3.0 with automatic format detection based on file extensions.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Path Parameters
- **INPUT** (string) - Required - Path to Swagger 2.0 file (.json or .yaml/.yml).
- **OUTPUT** (string) - Optional - Path to write OpenAPI 3.0 result. Format is determined by the file extension (.yaml/.yml for YAML, anything else for JSON). Writes JSON to STDOUT if omitted.

### Request Example
```bash
# JSON to JSON conversion
swagger23 petstore.json openapi.json

# YAML to YAML conversion
swagger23 petstore.yaml openapi.yaml

# Cross-format conversion (YAML input to JSON output)
swagger23 petstore.yaml openapi.json

# Cross-format conversion (JSON input to YAML output)
swagger23 petstore.json openapi.yaml
```

### Response
#### Success Response (File Output)
- OpenAPI 3.0 specification file (JSON or YAML) is created at the specified OUTPUT path.

#### Response Example
(See Request Example for command structure; output is a file)

```

--------------------------------

### Ruby Library Usage for Swagger to OpenAPI Conversion

Source: https://github.com/qew7/swagger23/blob/master/README.md

Illustrates how to integrate the swagger23 gem into Ruby code for converting Swagger 2.0 specifications. Shows methods for converting Hashes, JSON/YAML strings, and parsing source data.

```ruby
require "swagger23"

# Hash → Hash
swagger_hash = JSON.parse(File.read("petstore.json"))
openapi_hash = Swagger23.convert(swagger_hash)
```

```ruby
# String (JSON or YAML) → JSON string
json_string = Swagger23.convert_string(File.read("swagger.yaml", encoding: "utf-8"))
```

```ruby
# String (JSON or YAML) → YAML string
yaml_string = Swagger23.convert_to_yaml(File.read("swagger.json", encoding: "utf-8"))
```

```ruby
# Parse only
hash = Swagger23.parse(source)
```

--------------------------------

### CLI: Convert Swagger 2.0 Files to OpenAPI 3.0

Source: https://context7.com/qew7/swagger23/llms.txt

Demonstrates basic command-line usage of Swagger23 for converting Swagger 2.0 files (JSON or YAML) to OpenAPI 3.0. It supports automatic format detection and cross-format conversions.

```bash
# JSON to JSON conversion
swagger23 petstore.json openapi.json

# YAML to YAML conversion
swagger23 petstore.yaml openapi.yaml

# Cross-format conversion (YAML input to JSON output)
swagger23 petstore.yaml openapi.json

# Cross-format conversion (JSON input to YAML output)
swagger23 petstore.json openapi.yaml
```

--------------------------------

### Parse JSON and YAML Content with Swagger23

Source: https://context7.com/qew7/swagger23/llms.txt

Demonstrates parsing both JSON and YAML formatted Swagger 2.0 content using the Swagger23.parse method. It shows how to access parsed data and highlights the gem's ability to auto-detect content type.

```ruby
require "swagger23"

# Parse JSON content
json_source = '{"swagger": "2.0", "info": {"title": "API", "version": "1.0"}}'
hash = Swagger23.parse(json_source)
puts hash["swagger"]  # => "2.0"

# Parse YAML contentyaml_source = <<~YAML
  swagger: "2.0"
  info:
    title: My API
    version: "1.0.0"
YAML
hash = Swagger23.parse(yaml_source)
puts hash["info"]["title"]  # => "My API"

# Auto-detection works for file content
# content = File.read("api-spec.yaml", encoding: "utf-8")
# hash = Swagger23.parse(content)

```

--------------------------------

### Rewrite $ref Paths from Swagger 2.0 to OpenAPI 3.0 Components

Source: https://context7.com/qew7/swagger23/llms.txt

Illustrates how the Swagger23 converter automatically rewrites all `$ref` paths from Swagger 2.0 definitions to OpenAPI 3.0 component paths. This ensures compatibility when migrating specifications.

```ruby
require "swagger23"
require "json"

# Swagger 2.0 with references
swagger_doc = {
  "swagger" => "2.0",
  "info" => { "title" => "API", "version" => "1.0" },
  "definitions" => {
    "Pet" => { "type" => "object", "properties" => { "name" => { "type" => "string" } } }
  },
  "paths" => {
    "/pets" => {
      "get" => {
        "responses" => {
          "200" => {
            "description" => "List of pets",
            "schema" => { "$ref" => "#/definitions/Pet" }
          }
        }
      }
    }
  }
}

openapi = Swagger23.convert(swagger_doc)

# References are rewritten:
# #/definitions/Pet         → #/components/schemas/Pet
# #/parameters/Foo          → #/components/parameters/Foo
# #/responses/Foo           → #/components/responses/Foo
# #/securityDefinitions/X   → #/components/securitySchemes/X

puts openapi["paths"]["/pets"]["get"]["responses"]["200"]["content"]["application/json"]["schema"]["$ref"]
# Output: #/components/schemas/Pet

```

--------------------------------

### Ruby API: Convert String Input to YAML Output

Source: https://context7.com/qew7/swagger23/llms.txt

Demonstrates the `Swagger23.convert_to_yaml` method, which parses a JSON or YAML string input and returns the converted OpenAPI 3.0 document specifically as a YAML string.

```ruby
require "swagger23"

# Convert JSON input to YAML output
json_content = File.read("swagger.json", encoding: "utf-8")
yaml_output = Swagger23.convert_to_yaml(json_content)
File.write("openapi.yaml", yaml_output)

# Convert YAML input to YAML output (with normalization)
yaml_content = File.read("swagger.yaml", encoding: "utf-8")
yaml_output = Swagger23.convert_to_yaml(yaml_content)
puts yaml_output
```

--------------------------------

### Convert Swagger 2.0 Form Data and File Uploads to OpenAPI 3.0

Source: https://context7.com/qew7/swagger23/llms.txt

Explains how the Swagger23 converter handles Swagger 2.0 `formData` parameters, including file uploads, by transforming them into OpenAPI 3.0 `requestBody` objects with `multipart/form-data` content.

```ruby
require "swagger23"
require "json"

swagger_doc = {
  "swagger" => "2.0",
  "info" => { "title" => "API", "version" => "1.0" },
  "paths" => {
    "/upload" => {
      "post" => {
        "consumes" => ["multipart/form-data"],
        "parameters" => [
          { "in" => "formData", "name" => "file", "type" => "file", "required" => true },
          { "in" => "formData", "name" => "description", "type" => "string" }
        ],
        "responses" => { "200" => { "description" => "Uploaded" } }
      }
    }
  }
}

openapi = Swagger23.convert(swagger_doc)

# formData parameters become requestBody with multipart/form-data
request_body = openapi["paths"]["/upload"]["post"]["requestBody"]
puts JSON.pretty_generate(request_body)
# Output:
# {
#   "content": {
#     "multipart/form-data": {
#       "schema": {
#         "type": "object",
#         "properties": {
#           "file": { "type": "string", "format": "binary" },
#           "description": { "type": "string" }
#         },
#         "required": ["file"]
#       }
#     }
#   }
# }

```

--------------------------------

### Convert Swagger 2.0 Body Parameters to OpenAPI 3.0 requestBody

Source: https://context7.com/qew7/swagger23/llms.txt

Demonstrates the conversion of Swagger 2.0 `in: body` parameters into OpenAPI 3.0 `requestBody` objects. This is crucial for adapting API specifications to the newer OpenAPI standard.

```ruby
require "swagger23"
require "json"

swagger_doc = {
  "swagger" => "2.0",
  "info" => { "title" => "API", "version" => "1.0" },
  "consumes" => ["application/json"],
  "paths" => {
    "/pets" => {
      "post" => {
        "parameters" => [
          {
            "in" => "body",
            "name" => "pet",
            "required" => true,
            "description" => "Pet to create",
            "schema" => { "$ref" => "#/definitions/Pet" }
          }
        ],
        "responses" => { "201" => { "description" => "Created" } }
      }
    }
  },
  "definitions" => {
    "Pet" => { "type" => "object" }
  }
}

openapi = Swagger23.convert(swagger_doc)

# Body parameter becomes requestBody
request_body = openapi["paths"]["/pets"]["post"]["requestBody"]
puts JSON.pretty_generate(request_body)
# Output:
# {
#   "content": {
#     "application/json": {
#       "schema": { "$ref": "#/components/schemas/Pet" }
#     }
#   },
#   "description": "Pet to create",
#   "required": true
# }

```

--------------------------------

### Convert Swagger 2.0 Security Definitions to OpenAPI 3.0 Security Schemes (Ruby)

Source: https://context7.com/qew7/swagger23/llms.txt

This snippet demonstrates how the Swagger23 converter transforms Swagger 2.0 security definitions (BasicAuth, ApiKey, OAuth2) into OpenAPI 3.0 security schemes, including OAuth2 flows. It shows the conversion of 'securityDefinitions' to 'components.securitySchemes'.

```ruby
require "swagger23"
require "json"

swagger_doc = {
  "swagger" => "2.0",
  "info" => { "title" => "API", "version" => "1.0" },
  "securityDefinitions" => {
    "BasicAuth" => { "type" => "basic" },
    "ApiKey" => { "type" => "apiKey", "name" => "X-API-Key", "in" => "header" },
    "OAuth2" => {
      "type" => "oauth2",
      "flow" => "accessCode",
      "authorizationUrl" => "https://auth.example.com/authorize",
      "tokenUrl" => "https://auth.example.com/token",
      "scopes" => { "read" => "Read access", "write" => "Write access" }
    }
  },
  "paths" => {}
}
openapi = Swagger23.convert(swagger_doc)

# Security definitions become components/securitySchemes
schemes = openapi["components"]["securitySchemes"]
puts JSON.pretty_generate(schemes)
# Output shows conversions:
# - basic → http with scheme: basic
# - apiKey → apiKey (unchanged)
# - oauth2 accessCode → oauth2 with flows.authorizationCode
```

--------------------------------

### Ruby API: Convert Swagger Hash to OpenAPI Hash

Source: https://context7.com/qew7/swagger23/llms.txt

Demonstrates the core Ruby library function `Swagger23.convert` for programmatically converting a parsed Swagger 2.0 Ruby Hash into an OpenAPI 3.0 Ruby Hash.

```ruby
require "swagger23"
require "json"

# Read and parse the Swagger 2.0 document
swagger_hash = JSON.parse(File.read("petstore.json"))

# Convert to OpenAPI 3.0openapi_hash = Swagger23.convert(swagger_hash)

# Access the converted structure
puts openapi_hash["openapi"]  # => "3.0.3"
puts openapi_hash["info"]["title"]
puts openapi_hash["servers"].first["url"]
puts openapi_hash["paths"].keys
puts openapi_hash["components"]["schemas"].keys

# Write the result
File.write("openapi.json", JSON.pretty_generate(openapi_hash))
```

--------------------------------

### Ruby Library API - Swagger23.convert_to_yaml(source)

Source: https://context7.com/qew7/swagger23/llms.txt

Parses a JSON or YAML string and returns the converted OpenAPI 3.0 document as a YAML string.

```APIDOC
## Ruby Library API - Swagger23.convert_to_yaml(source)

Parses a JSON or YAML string and returns the converted OpenAPI 3.0 document as a YAML string.

### Method
`Swagger23.convert_to_yaml(source)`

### Endpoint
N/A (Ruby method)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **source** (String) - Required - A string containing the Swagger 2.0 specification in JSON or YAML format.

### Request Example
```ruby
require "swagger23"

# Convert JSON input to YAML output
json_content = File.read("swagger.json", encoding: "utf-8")
yaml_output = Swagger23.convert_to_yaml(json_content)
File.write("openapi.yaml", yaml_output)

# Convert YAML input to YAML output (with normalization)
yaml_content = File.read("swagger.yaml", encoding: "utf-8")
yaml_output = Swagger23.convert_to_yaml(yaml_content)
puts yaml_output
```

### Response
#### Success Response (String)
- **yaml_output** (String) - A YAML string representing the converted OpenAPI 3.0 specification.

#### Response Example
```yaml
openapi: 3.0.3
info:
  title: Swagger Petstore
  version: 1.0.0
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          description: A list of pets.
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
```
```

--------------------------------

### Ruby Library API - Swagger23.parse(source)

Source: https://context7.com/qew7/swagger23/llms.txt

Parses a JSON or YAML string into a Ruby Hash with automatic format detection based on the first non-whitespace character.

```APIDOC
## Ruby Library API - Swagger23.parse(source)

Parses a JSON or YAML string into a Ruby Hash with automatic format detection based on the first non-whitespace character.

### Method
`Swagger23.parse(source)`

### Endpoint
N/A (Ruby method)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **source** (String) - Required - A string containing the Swagger 2.0 specification in JSON or YAML format.

### Request Example
```ruby
require "swagger23"

# Parse JSON string
j = "{\"swagger\": \"2.0\", \"info\": { \"title\": \"My API\", \"version\": \"1.0.0\" }}"
hash_from_json = Swagger23.parse(j)
puts hash_from_json["swagger"] # => "2.0"

# Parse YAML string
y = "swagger: '2.0'\ninfo:\n  title: My YAML API\n  version: 1.0.0"
hash_from_yaml = Swagger23.parse(y)
puts hash_from_yaml["swagger"] # => "2.0"
```

### Response
#### Success Response (Hash)
- **parsed_hash** (Hash) - A Ruby Hash representing the parsed Swagger 2.0 specification.

#### Response Example
```ruby
# Example for parsing JSON
{
  "swagger": "2.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  }
}

# Example for parsing YAML
{
  "swagger": "2.0",
  "info": {
    "title": "My YAML API",
    "version": "1.0.0"
  }
}
```
```

--------------------------------

### Ruby Library API - Swagger23.convert_string(source)

Source: https://context7.com/qew7/swagger23/llms.txt

Parses a JSON or YAML string and returns the converted OpenAPI 3.0 document as a pretty-printed JSON string. Ideal for one-liner conversions.

```APIDOC
## Ruby Library API - Swagger23.convert_string(source)

Parses a JSON or YAML string and returns the converted OpenAPI 3.0 document as a pretty-printed JSON string. Ideal for one-liner conversions.

### Method
`Swagger23.convert_string(source)`

### Endpoint
N/A (Ruby method)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **source** (String) - Required - A string containing the Swagger 2.0 specification in JSON or YAML format.

### Request Example
```ruby
require "swagger23"

# Convert from YAML file content to JSON string
yaml_content = File.read("swagger.yaml", encoding: "utf-8")
json_output = Swagger23.convert_string(yaml_content)
puts json_output
# Output: Pretty-printed JSON OpenAPI 3.0 document

# Convert from JSON file content to JSON string
json_content = File.read("swagger.json", encoding: "utf-8")
json_output = Swagger23.convert_string(json_content)
File.write("openapi.json", json_output)
```

### Response
#### Success Response (String)
- **json_output** (String) - A pretty-printed JSON string representing the converted OpenAPI 3.0 specification.

#### Response Example
```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Swagger Petstore",
    "version": "1.0.0"
  },
  "paths": {
    "/pets": {
      "get": {
        "summary": "List all pets",
        "responses": {
          "200": {
            "description": "A list of pets."
          }
        }
      }
    }
  }
}
```
```

--------------------------------

### Ruby API: Parse JSON or YAML String

Source: https://context7.com/qew7/swagger23/llms.txt

Explains the `Swagger23.parse` method, which takes a JSON or YAML string as input and automatically detects the format to parse it into a Ruby Hash.

```ruby
require "swagger23"

```

--------------------------------

### Handle Nullable Properties from x-nullable and Type Arrays to OpenAPI 3.0 (Ruby)

Source: https://context7.com/qew7/swagger23/llms.txt

This snippet shows the Swagger23 converter's ability to transform Swagger 2.0 'x-nullable' extensions and type arrays (e.g., ['string', 'null']) into the OpenAPI 3.0 'nullable' property. It processes definitions to correctly set the nullable attribute for schema properties.

```ruby
require "swagger23"
require "json"

swagger_doc = {
  "swagger" => "2.0",
  "info" => { "title" => "API", "version" => "1.0" },
  "definitions" => {
    "User" => {
      "type" => "object",
      "properties" => {
        "email" => { "type" => "string", "x-nullable" => true },
        "nickname" => { "type" => ["string", "null"] }
      }
    }
  },
  "paths" => {}
}

openapi = Swagger23.convert(swagger_doc)

schema = openapi["components"]["schemas"]["User"]["properties"]
puts JSON.pretty_generate(schema)
# Output:
# {
#   "email": { "type": "string", "nullable": true },
#   "nickname": { "type": "string", "nullable": true }
# }
```

--------------------------------

### Ruby API: Convert String Input to JSON Output

Source: https://context7.com/qew7/swagger23/llms.txt

Utilizes the `Swagger23.convert_string` method to parse a JSON or YAML string input and return the converted OpenAPI 3.0 document as a pretty-printed JSON string, suitable for one-liner conversions.

```ruby
require "swagger23"

# Convert from YAML file content to JSON string
yaml_content = File.read("swagger.yaml", encoding: "utf-8")
json_output = Swagger23.convert_string(yaml_content)
puts json_output
# Output: Pretty-printed JSON OpenAPI 3.0 document

# Convert from JSON file content to JSON string
json_content = File.read("swagger.json", encoding: "utf-8")
json_output = Swagger23.convert_string(json_content)
File.write("openapi.json", json_output)
```

--------------------------------

### Handle Swagger23 Conversion Errors

Source: https://context7.com/qew7/swagger23/llms.txt

Provides a robust error handling mechanism for Swagger 2.0 parsing and conversion using the Swagger23 gem. It catches specific error types like InvalidSwaggerError and general parse errors, allowing for precise failure management.

```ruby
require "swagger23"
require "json"

begin
  # Attempt to parse and convert
  content = File.read("swagger.json", encoding: "utf-8")
  swagger = Swagger23.parse(content)
  openapi = Swagger23.convert(swagger)
  puts JSON.pretty_generate(openapi)
rescue Swagger23::InvalidSwaggerError => e
  # Raised when swagger version is not "2.0"
  warn "Invalid Swagger document: #{e.message}"
  # Example: "Expected swagger version '2.0', got '3.0'. Only Swagger 2.0 documents are supported."
  exit 2
rescue Swagger23::Error => e
  # Raised for parse errors (invalid JSON/YAML)
  warn "Parse error: #{e.message}"
  # Example: "JSON parse error: unexpected token at '...'"
  # Example: "Could not parse input as YAML: ..."
  exit 1
rescue => e
  # Unexpected errors
  warn "Unexpected error: #{e.class}: #{e.message}"
  exit 3
end

```

--------------------------------

### Ruby Library API - Swagger23.convert(swagger_hash)

Source: https://context7.com/qew7/swagger23/llms.txt

Converts a parsed Swagger 2.0 Hash directly to an OpenAPI 3.0 Hash. This is the core conversion method for programmatic use within Ruby applications.

```APIDOC
## Ruby Library API - Swagger23.convert(swagger_hash)

Converts a parsed Swagger 2.0 Hash directly to an OpenAPI 3.0 Hash. This is the core conversion method for programmatic use.

### Method
`Swagger23.convert(swagger_hash)`

### Endpoint
N/A (Ruby method)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **swagger_hash** (Hash) - Required - A Ruby Hash representing the parsed Swagger 2.0 specification.

### Request Example
```ruby
require "swagger23"
require "json"

# Read and parse the Swagger 2.0 document
swagger_hash = JSON.parse(File.read("petstore.json"))

# Convert to OpenAPI 3.0
openapi_hash = Swagger23.convert(swagger_hash)

# Access the converted structure
puts openapi_hash["openapi"]  # => "3.0.3"
puts openapi_hash["info"]["title"]
puts openapi_hash["servers"].first["url"]
puts openapi_hash["paths"].keys
puts openapi_hash["components"]["schemas"].keys

# Write the result
File.write("openapi.json", JSON.pretty_generate(openapi_hash))
```

### Response
#### Success Response (Hash)
- **openapi_hash** (Hash) - A Ruby Hash representing the converted OpenAPI 3.0 specification.

#### Response Example
```ruby
# Example output structure (partial)
{
  "openapi": "3.0.3",
  "info": {
    "title": "Swagger Petstore",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "http://petstore.swagger.io/v1"
    }
  ],
  "paths": {
    "/pets": {
      "get": {
        "summary": "List all pets",
        "responses": {
          "200": {
            "description": "A list of pets."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pet": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "name": {
            "type": "string"
          },
          "tag": {
            "type": "string"
          }
        }
      }
    }
  }
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.