openapi3_parser 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dc74c9c6170cb4f0bd73f5debc10b7a53317c3f4
-  data.tar.gz: ffd75a8d5d5ff4d1f40493331645db2785810eb6
+  metadata.gz: c9c582d931f4f1353ee60c24d7197af410b6a0fe
+  data.tar.gz: 99f57e7b4ed9c359a769dbaff78a82bdeac13e55
 SHA512:
-  metadata.gz: a9c5641522434bb630c27679dcf7a9a93ab3c538e7cbc45597e84f72ba8cdb3ed7d6477cdeee3623becda92a02fa118073e7dcac61780a5d6bab112a763fd75f
-  data.tar.gz: 07b6ad8941ab2a02b210a25f278287cd7d29f3025b529d540e9fd5ff973e6d51938e2618b085eb3970e79757f21dca9629d6bd4c472f77f29b24493b82c6cb85
+  metadata.gz: 880d452e266f6dae6c14083ce278f21f469843e2952e0df3f3a5a11222fe0c9bb2042a2d5a0d7209eab83249556fb01f708bf2ffa624ac7838270199efaeb8a6
+  data.tar.gz: 0c4980179959a775d12d913dec31896307e9712ef2ea3585eeba71f2e9fd6bd1ebbaafa90c0b00b1e5fd61967b83131f7e2773a9a7bd0e481e47b5c4922343c2

data/.ruby-version

@@ -1 +1 @@
-2.3.1
+2.4.6

data/.travis.yml

@@ -1,9 +1,9 @@
 language: ruby
 sudo: false
 rvm:
-  - 2.3.7
-  - 2.4.4
-  - 2.5.1
+  - 2.4.6
+  - 2.5.5
+  - 2.6.4
   - ruby-head
 matrix:
   allow_failures:

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+# 0.6.0
+
+- Drop support for Ruby 2.3
+- Re-use references for significantly faster initialisation and validation
+- Only error when accessing an invalid node rather than at root
+- Handle infinitely recursive references that never resolve
+
 # 0.5.2
 
 - Fix outputting warnings for cyclic dependencies and undefined variables -
@@ -34,4 +41,3 @@
 - Allow defaulting to empty arrays and maps
 - Configure rubydoc
 - Types returned documented for the nodes
-

data/README.md

@@ -2,47 +2,134 @@
 
 [![Build Status](https://travis-ci.org/kevindew/openapi3_parser.svg?branch=master)](https://travis-ci.org/kevindew/openapi3_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].
 
-This is a parser/validator for [Open API 3][openapi-3] built in Ruby.
+Basic example:
 
-Example usage:
-
-```
+```ruby
 require "openapi3_parser"
 
-document = Openapi3Parser.load_file("path/to/example.yaml")
+document = Openapi3Parser.load_url("https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml")
 
-# check whether document is valid
-document.valid?
-
-# traverse document
-document.paths["/"]
+document.paths["/pets"].get.summary
+# => "List all pets"
 ```
 
-Documentation for the API to navigate the OpenAPI nodes is available on
-[rubydoc.info][docs].
+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].
+
 
 [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
 
+## Usage
+
+### Loading a specification
+
+```ruby
+# by URL
+Openapi3Parser.load_url("https://raw.githubusercontent.com/kevindew/openapi3_parser/master/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/master/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.5.0"
+gem "openapi3_parser", "~> 0.6.0"
 ```
 
 and then running `$ bundle install`
 
-Or install the gem onto your machine via ` $ gem install openapi3_parser`
+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 roadmap there.
+See [TODO](TODO.md) for details of the features still to implement.
 
 ## Licence
 

data/lib/openapi3_parser/document.rb

@@ -80,8 +80,8 @@ module Openapi3Parser
 
     # @param [SourceInput] source_input
     def initialize(source_input)
-      @reference_register = ReferenceRegister.new
-      @root_source = Source.new(source_input, self, reference_register)
+      @reference_registry = ReferenceRegistry.new
+      @root_source = Source.new(source_input, self, reference_registry)
       @warnings = []
       @openapi_version = determine_openapi_version(root_source.data["openapi"])
       @build_in_progress = false
@@ -90,7 +90,7 @@ module Openapi3Parser
 
     # @return [Node::Openapi]
     def root
-      factory.node
+      @root ||= factory.node(Node::Context.root(factory.context))
     end
 
     # All the additional sources that have been referenced as part of loading
@@ -99,7 +99,7 @@ module Openapi3Parser
     # @return [Array<Source>]
     def reference_sources
       build unless built
-      reference_register.sources
+      reference_registry.sources.reject(&:root?)
     end
 
     # All of the sources involved in this OpenAPI document
@@ -131,8 +131,8 @@ module Openapi3Parser
     # resolved_input refers to the input with references resolevd and all
     # optional fields existing
     #
-    # @param [Context::Pointer, String, Array]      pointer
-    # @param [Context::Pointer, String, Array, nil] relative_to
+    # @param [Source::Pointer, String, Array]      pointer
+    # @param [Source::Pointer, String, Array, nil] relative_to
     # @return anything
     def resolved_input_at(pointer, relative_to = nil)
       look_up_pointer(pointer, relative_to, factory.resolved_input)
@@ -145,8 +145,8 @@ module Openapi3Parser
     # document.node_at("#/components/schemas")
     # document.node_at(%w[components schemas])
     #
-    # @param [Context::Pointer, String, Array]      pointer
-    # @param [Context::Pointer, String, Array, nil] relative_to
+    # @param [Source::Pointer, String, Array]      pointer
+    # @param [Source::Pointer, String, Array, nil] relative_to
     # @return anything
     def node_at(pointer, relative_to = nil)
       look_up_pointer(pointer, relative_to, root)
@@ -160,11 +160,11 @@ module Openapi3Parser
 
     private
 
-    attr_reader :reference_register, :built, :build_in_progress
+    attr_reader :reference_registry, :built, :build_in_progress
 
     def look_up_pointer(pointer, relative_pointer, subject)
-      merged_pointer = Context::Pointer.merge_pointers(relative_pointer,
-                                                       pointer)
+      merged_pointer = Source::Pointer.merge_pointers(relative_pointer,
+                                                      pointer)
       CautiousDig.call(subject, *merged_pointer.segments)
     end
 
@@ -175,9 +175,9 @@ module Openapi3Parser
     def build
       return if build_in_progress || built
       @build_in_progress = true
-      context = Context.root(root_source.data, root_source)
+      context = NodeFactory::Context.root(root_source.data, root_source)
       @factory = NodeFactory::Openapi.new(context)
-      reference_register.freeze
+      reference_registry.freeze
       @warnings.freeze
       @build_in_progress = false
       @built = true
@@ -210,7 +210,7 @@ module Openapi3Parser
 
     def reference_factories
       build unless built
-      reference_register.factories
+      reference_registry.factories.reject { |f| f.context.source.root? }
     end
   end
 end

data/lib/openapi3_parser/document/reference_registry.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Openapi3Parser
+  class Document
+    class ReferenceRegistry
+      attr_reader :sources
+
+      def initialize
+        @sources = []
+        @factories_by_type = {}
+      end
+
+      def freeze
+        sources.freeze
+        factories_by_type.freeze.each(&:freeze)
+        super
+      end
+
+      def factories
+        factories_by_type.values.flatten
+      end
+
+      def register(unbuilt_factory, source_location, reference_factory_context)
+        register_source(source_location.source)
+        object_type = unbuilt_factory.object_type
+        existing_factory = factory(object_type, source_location)
+
+        return existing_factory if existing_factory
+
+        build_factory(
+          unbuilt_factory,
+          source_location,
+          reference_factory_context
+        ).tap { |f| register_factory(object_type, f) }
+      end
+
+      def factory(object_type, source_location)
+        factories_by_type[object_type]&.find do |f|
+          f.context.source_location == source_location
+        end
+      end
+
+      private
+
+      attr_reader :factories_by_type
+
+      def register_source(source)
+        sources << source unless sources.include?(source)
+      end
+
+      def register_factory(object_type, factory)
+        factories_by_type[object_type] ||= []
+        factories_by_type[object_type] << factory
+      end
+
+      def build_factory(unbuilt_factory,
+                        source_location,
+                        reference_factory_context)
+        next_context = NodeFactory::Context.resolved_reference(
+          reference_factory_context,
+          source_location: source_location
+        )
+
+        if unbuilt_factory.is_a?(Class)
+          unbuilt_factory.new(next_context)
+        else
+          unbuilt_factory.call(next_context)
+        end
+      end
+    end
+  end
+end

data/lib/openapi3_parser/node/array.rb

@@ -14,7 +14,7 @@ module Openapi3Parser
       extend Forwardable
       include Enumerable
 
-      def_delegators :node_data, :each, :[], :empty?
+      def_delegators :node_data, :empty?
       attr_reader :node_data, :node_context
 
       # @param [::Array] data     data used to populate this node
@@ -24,8 +24,16 @@ module Openapi3Parser
         @node_context = context
       end
 
+      def [](index)
+        Placeholder.resolve(node_data[index])
+      end
+
+      def each
+        node_data.each_index { |index| yield(self[index]) }
+      end
+
       # Used to access a node relative to this node
-      # @param  [Context::Pointer, ::Array, ::String] pointer_like
+      # @param  [Source::Pointer, ::Array, ::String] pointer_like
       # @return anything
       def node_at(pointer_like)
         current_pointer = node_context.document_location.pointer

data/lib/openapi3_parser/node/components.rb

@@ -8,47 +8,47 @@ module Openapi3Parser
     class Components < Node::Object
       # @return [Map<String, Schema>]
       def schemas
-        node_data["schemas"]
+        self["schemas"]
       end
 
       # @return [Map<String, Response>]
       def responses
-        node_data["responses"]
+        self["responses"]
       end
 
       # @return [Map<String, Parameter>]
       def parameters
-        node_data["parameters"]
+        self["parameters"]
       end
 
       # @return [Map<String, Example>]
       def examples
-        node_data["examples"]
+        self["examples"]
       end
 
       # @return [Map<String, RequestBody>]
       def request_bodies
-        node_data["requestBodies"]
+        self["requestBodies"]
       end
 
       # @return [Map<String, Header>]
       def headers
-        node_data["headers"]
+        self["headers"]
       end
 
       # @return [Map<String, SecurityScheme>]
       def security_schemes
-        node_data["securitySchemes"]
+        self["securitySchemes"]
       end
 
       # @return [Map<String, Link>]
       def links
-        node_data["links"]
+        self["links"]
       end
 
       # @return [Map<String, Callback>]
       def callbacks
-        node_data["callbacks"]
+        self["callbacks"]
       end
     end
   end

data/lib/openapi3_parser/node/contact.rb

@@ -8,17 +8,17 @@ module Openapi3Parser
     class Contact < Node::Object
       # @return [String, nil]
       def name
-        data["name"]
+        self["name"]
       end
 
       # @return [String, nil]
       def url
-        data["url"]
+        self["url"]
       end
 
       # @return [String, nil]
       def email
-        data["email"]
+        self["email"]
       end
     end
   end