swagger23

A Ruby gem that converts Swagger 2.0 API specifications into OpenAPI 3.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:

gem "swagger23"

Then run:

bundle install

Or install globally:

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:

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

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

bundle exec rspec

---

Contributing

1. Fork 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.

---

Author

Maxim Veysgeym — Ruby enthusiast, Moscow.

---

License

Released under the MIT License © 2026 Maxim Veysgeym.