Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kevindew/openapi3_parser
Open API 3 Parser/Validator for Ruby
https://github.com/kevindew/openapi3_parser
openapi openapi-specification parser ruby
Last synced: 1 day ago
JSON representation
Open API 3 Parser/Validator for Ruby
- Host: GitHub
- URL: https://github.com/kevindew/openapi3_parser
- Owner: kevindew
- License: mit
- Created: 2017-10-19T23:33:52.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2024-05-21T08:44:47.000Z (6 months ago)
- Last Synced: 2024-10-31T01:06:11.254Z (15 days ago)
- Topics: openapi, openapi-specification, parser, ruby
- Language: Ruby
- Homepage:
- Size: 1020 KB
- Stars: 91
- Watchers: 8
- Forks: 12
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# OpenAPI 3 Parser
This a Ruby based parser/validator for [OpenAPI 3][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][openapi-3-spec].
Basic example:
```ruby
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][docs].
I've wrote a blog post reflecting on the decisions involved in building this
parser in [How to write an OpenAPI 3 parser][blog].
[openapi-3]: https://github.com/OAI/OpenAPI-Specification
[openapi-3-spec]: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#specification
[docs]: http://www.rubydoc.info/github/kevindew/openapi3_parser/Openapi3Parser/Node/Openapi
[blog]: https://kevindew.me/post/188611423231/how-to-write-an-openapi-3-parser
## Usage
### Loading a specification
```ruby
# 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
```ruby
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
```ruby
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][docs]
## 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](TODO.md) for details of the features still to implement.
## Licence
[MIT License](LICENCE)