openapi3_parser

OpenAPI 3 Parser

This a Ruby based parser/validator for OpenAPI 3. It is used to convert an OpenAPI file (can be a local file, a URL, a string or even a Ruby hash) into an object graph with a simple API that follows the OpenAPI specification.

Basic example:

require "openapi3_parser"

document = Openapi3Parser.load_url("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml")

document.paths["/pets"].get.summary
# => "List all pets"

It aims to support 100% of the OpenAPI 3.0 specification, with key features being:

• Supports loading a specification by path to a file, URL, Ruby file objects, and strings in YAML and JSON formats, it even supports loading via a Ruby hash;
• Support for loading references from external files including URLs;
• Handles recursive references;
• All of OpenAPI specification mapped to Ruby objects, providing a natural Ruby interface that maps clearly to the specification;
• OpenAPI files validated with a simple API to quickly and simply see all problems with a file
• Built-in Markdown to HTML conversion;
• Documentation for the API to navigate the OpenAPI nodes is available on rubydoc.info.

I've wrote a blog post reflecting on the decisions involved in building this parser in How to write an OpenAPI 3 parser.

Usage

Loading a specification

# by URL
Openapi3Parser.load_url("https://raw.githubusercontent.com/kevindew/openapi3_parser/main/spec/support/examples/petstore-expanded.yaml")

# by path to file
Openapi3Parser.load_file("spec/support/examples/uber.yaml")

# by File
Openapi3Parser.load(File.open("spec/support/examples/uber.yaml"))

# by String
Openapi3Parser.load('{ "openapi": "3.0.0", "info": { "title": "API", "version": "1.0.0" }, "paths": {}  }')

# by Hash
Openapi3Parser.load(openapi: "3.0.0", info: { title: "API", version: "1.0.0" }, paths: {})

Validating

document = Openapi3Parser.load(openapi: "3.0.0", info: {}, paths: {})
document.valid?
# => false
document.errors
# => Openapi3Parser::Validation::ErrorCollection(errors: {"#/info"=>["Missing required fields: title and version"]})

Traversing

document = Openapi3Parser.load_url("https://raw.githubusercontent.com/kevindew/openapi3_parser/main/spec/support/examples/petstore-expanded.yaml")

# by objects

document.info.terms_of_service
# => "http://swagger.io/terms/"

document.paths.keys
# => ["/pets", "/pets/{id}"]

document.paths["/pets"].get.parameters.map(&:name)
# => ["tags", "limit"]

# by hash syntax

document["info"]["termsOfService"]
=> "http://swagger.io/terms/"

document["paths"].keys
# => ["/pets", "/pets/{id}"]

document["paths"]["/pets"]["get"]["parameters"].map(&:name)
# => ["tags", "limit"]

# by a path to a node
document.node_at("#/paths/%2Fpets/get/operationId")
=> "findPets"

document.node_at("#/components/schemas/Pet/allOf/0/required/0")
=> "name"

# or combining

document.components.schemas["Pet"].node_at("#../NewPet")
=> Openapi3Parser::Node::Schema(#/components/schemas/NewPet)

You can learn more about the API on rubydoc.info

Installation

You can install this gem into your bundler application by adding this line to your Gemfile:

gem "openapi3_parser", "~> 0.10.0"

and then running $ bundle install

Or install the gem onto your machine via $ gem install openapi3_parser

Status

This is currently a work in progress and will remain so until it reaches 1.0.

See TODO for details of the features still to implement.

Licence

MIT License