openapi3_parser 0.6.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ca568bd4f56414a9a7467ba929750fe26ebe2ff6
-  data.tar.gz: 3e0a2532c02e114140e3ea53458e637308b1ab53
+SHA256:
+  metadata.gz: 81001258de6af8c21c8a7db87520d9433e3acb878483a56a616fdcd804e92848
+  data.tar.gz: 496f3a02ebcb386e949eab7ec6607f360a0b2e755be6bb4f1df3cd6b260a6e0d
 SHA512:
-  metadata.gz: 916678f780b8d71fd83c09a64fc6725e678dd8356a137d4b7295c7c4ca185d824c4803bae74c46de755faa5c52736ddcbada93fc0c88ef12d8b2e0e583edc56a
-  data.tar.gz: effde9d9458daf6d68bc5c9d79d137c32d583246f620f039b4606f1cf678d6f10bea2553a23b0930b2b73ecb0a665a66c9f5ac227e15956629095746363d634e
+  metadata.gz: d789d4ffe423f8854f961e902ffa6ef56b86d7dbcf506292106afa8548b72f2fbe968d98358ea7c80771a3c2e974c302096d43968c0663bdad40dc5f60a676e2
+  data.tar.gz: aea92fa77fbb4808872093b9149f8eb933f70a38336a0e415fa1fc9d4c15e691b8307abb0d70c0e51eee8eca89887cbc1a16b21e70f2d1812ae0fd77b75fe2a3

data/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+on: [push, pull_request]
+jobs:
+  test:
+    strategy:
+      matrix:
+        ruby: [2.5, 2.6, 2.7, 3.0]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: ${{ matrix.ruby }}
+      - name: Test Ruby ${{ matrix.ruby }}
+        run: bundle exec rake
+        if: matrix.ruby != '2.5'
+      - name: Test and publish coverage for Ruby ${{ matrix.ruby }}
+        uses: paambaati/codeclimate-action@v2.7.5
+        env:
+          CC_TEST_REPORTER_ID: 8bc2d8e54331569aeb442094c21cb64a58d6efa0670f65ff00d9ae887f63c0b4
+        with:
+          coverageCommand: bundle exec rake
+        if: matrix.ruby == '2.5'

data/.gitignore

@@ -2,3 +2,4 @@
 /pkg
 /.yardoc
 /doc
+/coverage

data/.rubocop.yml

@@ -1,15 +1,30 @@
+require:
+  - rubocop-rake
+  - rubocop-rspec
+AllCops:
+  NewCops: enable
 Style/StringLiterals:
   EnforcedStyle: double_quotes
 Metrics/MethodLength:
   Max: 30
 Metrics/AbcSize:
   Max: 30
-Documentation:
+RSpec/ExampleLength:
+  Max: 30
+Style/Documentation:
   Enabled: false
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*.rb'
-Naming/UncommunicativeMethodParamName:
+    - '*.gemspec'
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/integration/**/*.rb'
+# I'd rather have multiple expectations than lots of duplicate tests
+RSpec/MultipleExpectations:
+  Enabled: false
+# The default arbitrary number (5) is a little painful
+RSpec/MultipleMemoizedHelpers:
   Enabled: false
-Naming/UncommunicativeBlockParamName:
+RSpec/MessageSpies:
   Enabled: false

data/.ruby-version

@@ -1 +1 @@
-2.4.6
+2.5.8

data/CHANGELOG.md

@@ -1,3 +1,44 @@
+# 0.9.0
+
+- Fix unexpected fields error when using Example nodes inside a Parameter -
+  https://github.com/kevindew/openapi3_parser/pull/19
+- Drop support for Ruby 2.4
+
+# 0.8.2
+
+- Fix bug falling into recursive loop on Array/Map nodes -
+  https://github.com/kevindew/openapi3_parser/issues/13
+
+# 0.8.1
+
+- Fix incorrectly spelt method name on `Schema` s/disciminator/discriminator/g
+
+# 0.8.0
+
+- Resolve deprecation warnings for Ruby 2.7
+- Resolve deprecation warnings for Psych
+- Operation and Path Item objects use servers that have cascaded from parent
+  objects if they do not have their own servers defined.
+- Add `#relative_node` and `#parent_node` methods to `Node::Context`.
+- Default to a server of "/" when given an empty or null servers input for
+  OpenAPI node.
+- Set referenced data as input and source location for a PathItem with only
+  a $ref value.
+- Fix data being lost in PathItem reference merges.
+
+# 0.7.0
+
+- Add `#values` method to `Node::Object` and `Node#Map` to have a method that
+  pairs with `#keys`
+- Add `Node::Schema#requires?` method to simplify checking whether a property
+  is required by a particular schema.
+- Add `#==` methods to Node objects. This allows checking whether two nodes
+  are from the same source location even if they're referenced in different
+  places.
+- Add `Node::Schema#name` method that looks up the name of a Schema based
+  on it's contextual position in a document. Allows accessing the `Pet` value
+  from `#/components/schemas/Pet`.
+
 # 0.6.1
 
 - Fix bug where Node::Object and Node::Map iterated arrays rather than hashes

data/README.md

@@ -1,6 +1,6 @@
 # OpenAPI 3 Parser
 
-[![Build Status](https://travis-ci.org/kevindew/openapi3_parser.svg?branch=master)](https://travis-ci.org/kevindew/openapi3_parser)
+[![Build Status](https://travis-ci.org/kevindew/openapi3_parser.svg?branch=main)](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
@@ -33,10 +33,13 @@ being:
 - 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
 
@@ -44,7 +47,7 @@ being:
 
 ```ruby
 # by URL
-Openapi3Parser.load_url("https://raw.githubusercontent.com/kevindew/openapi3_parser/master/spec/support/examples/petstore-expanded.yaml")
+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")
@@ -73,7 +76,7 @@ document.errors
 ### Traversing
 
 ```ruby
-document = Openapi3Parser.load_url("https://raw.githubusercontent.com/kevindew/openapi3_parser/master/spec/support/examples/petstore-expanded.yaml")
+document = Openapi3Parser.load_url("https://raw.githubusercontent.com/kevindew/openapi3_parser/main/spec/support/examples/petstore-expanded.yaml")
 
 # by objects
 
@@ -118,7 +121,7 @@ You can install this gem into your bundler application by adding this line to
 your Gemfile:
 
 ```
-gem "openapi3_parser", "~> 0.6.0"
+gem "openapi3_parser", "~> 0.8.0"
 ```
 
 and then running `$ bundle install`

data/TODO.md

@@ -32,7 +32,7 @@ These are the steps defined to reach 1.0. Assistance is very welcome.
 - [x] Ensure Array and Map nodes return empty ones by default rather than nil
 - [ ] Make JSON pointer public access to be consistent accepting string, array
       or (potentially) a pointer class
-- [ ] Support creating a default Server object on servers property of OpenAPI
+- [x] Support creating a default Server object on servers property of OpenAPI
       Node
 - [ ] Support relative URLs being able to be relative the first server object
       see: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#relative-references-in-urls

data/lib/openapi3_parser.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-Dir.glob(File.join(__dir__, "openapi3_parser", "**", "*.rb")).each do |file|
-  require file
-end
+files = Dir.glob(File.join(__dir__, "openapi3_parser", "**", "*.rb")).sort
+files.each { |file| require file }
 
 module Openapi3Parser
   # For a variety of inputs this will construct an OpenAPI document. For a

data/lib/openapi3_parser/array_sentence.rb

@@ -5,7 +5,8 @@ module Openapi3Parser
     refine ::Array do
       def sentence_join
         return join if count < 2
-        self[0..-2].join(", ") + " and " + self[-1]
+
+        "#{self[0..-2].join(', ')} and #{self[-1]}"
       end
     end
   end

data/lib/openapi3_parser/document.rb

@@ -60,7 +60,7 @@ module Openapi3Parser
     # @!method external_docs
     #   The value of the external_docs field on the OpenAPI document
     #   @see Node::Openapi#external_docs
-    #   @return [Node::ExternalDocumentation]
+    #   @return [Node::ExternalDocumentation, nil]
     # @!method extension
     #   Look up an extension field provided for the root object of the document
     #   @see Node::Object#extension
@@ -138,7 +138,7 @@ module Openapi3Parser
       look_up_pointer(pointer, relative_to, factory.resolved_input)
     end
 
-    # Look up a node at a particular location in the OpenAPI docuemnt
+    # Look up a node at a particular location in the OpenAPI document
     #
     # Examples:
     #
@@ -174,6 +174,7 @@ module Openapi3Parser
 
     def build
       return if build_in_progress || built
+
       @build_in_progress = true
       context = NodeFactory::Context.root(root_source.data, root_source)
       @factory = NodeFactory::Openapi.new(context)

data/lib/openapi3_parser/error.rb

@@ -7,32 +7,42 @@ module Openapi3Parser
     # at runtime when we have tried to access that resource it is not available
     # for whatever reason.
     class InaccessibleInput < Error; end
+
     # Raised in cases where we provided data that we expected to be parsable
     # (such as a string of JSON data) but when we tried to parse it an error
     # is raised
     class UnparsableInput < Error; end
+
     # Raised in cases where an object that is in an immutable state is modified
     #
     # Typically this would occur when a component that is frozen is modififed.
     # Some components are mutable during the construction of a document and
     # then frozen afterwards.
     class ImmutableObject < Error; end
-    # Raised when a type that is not a whitelist of valid types is used
+
+    # Raised when a node is provided data as a type that is outside the allowed
+    # list
     class InvalidType < Error; end
+
     # Raised when we have to abort creating an object due to invalid data
     class InvalidData < Error; end
+
     # Used when there are fields that are missing from an object which prevents
     # us from creating a node
     class MissingFields < Error; end
+
     # Used when there are extra fields that are not expected in the data for
     # a node
     class UnexpectedFields < Error; end
+
     # Used when a method we expect to be able to call (through symbol or proc)
     # is not callable
     class NotCallable < Error; end
+
     # Raised when we in a recursive data structure and can't perform an
     # operation
     class InRecursiveStructure < Error; end
+
     # Used when we're trying to validate that a type is something that is not
     # validatable, most likely a sign that we're in a bug
     class UnvalidatableType < Error; end

data/lib/openapi3_parser/node/array.rb

@@ -14,7 +14,7 @@ module Openapi3Parser
       extend Forwardable
       include Enumerable
 
-      def_delegators :node_data, :empty?
+      def_delegators :node_data, :empty?, :length, :size
       attr_reader :node_data, :node_context
 
       # @param [::Array] data     data used to populate this node
@@ -35,6 +35,14 @@ module Openapi3Parser
         Placeholder.each(node_data, &block)
       end
 
+      # @param [Any]  other
+      #
+      # @return [Boolean]
+      def ==(other)
+        other.instance_of?(self.class) &&
+          node_context.same_data_and_source?(other.node_context)
+      end
+
       # Used to access a node relative to this node
       # @param  [Source::Pointer, ::Array, ::String] pointer_like
       # @return anything

data/lib/openapi3_parser/node/context.rb

@@ -65,10 +65,19 @@ module Openapi3Parser
         @source_location = source_location
       end
 
+      # @param  [Context] other
       # @return [Boolean]
       def ==(other)
+        document_location == other.document_location &&
+          same_data_and_source?(other)
+      end
+
+      # Check that contexts are the same without concern for document location
+      #
+      # @param  [Context] other
+      # @return [Boolean]
+      def same_data_and_source?(other)
         input == other.input &&
-          document_location == other.document_location &&
           source_location == other.source_location
       end
 
@@ -98,9 +107,7 @@ module Openapi3Parser
       def location_summary
         summary = document_location.to_s
 
-        if document_location != source_location
-          summary += " (#{source_location})"
-        end
+        summary += " (#{source_location})" if document_location != source_location
 
         summary
       end
@@ -124,6 +131,29 @@ module Openapi3Parser
       def node
         document.node_at(document_location.pointer)
       end
+
+      # Look up a node at a particular location in the OpenAPI docuemnt based
+      # on the relative position in the document of this context
+      #
+      # Examples:
+      #
+      # context.relative_node("#schemas")
+      # context.relative_node(%w[..])
+      #
+      # @param [Source::Pointer, String, Array] pointer
+      # @return anything
+      def relative_node(pointer)
+        document.node_at(pointer, document_location.pointer)
+      end
+
+      # Return the node that is the parent node for the node at this context
+      #
+      # @return [Node::Object, Node::Map, Node::Array, nil]
+      def parent_node
+        return if document_location.root?
+
+        relative_node("#..")
+      end
     end
   end
 end

data/lib/openapi3_parser/node/map.rb

@@ -8,7 +8,7 @@ module Openapi3Parser
       extend Forwardable
       include Enumerable
 
-      def_delegators :node_data, :keys, :empty?
+      def_delegators :node_data, :keys, :empty?, :length, :size
       attr_reader :node_data, :node_context
 
       def initialize(data, context)
@@ -48,6 +48,14 @@ module Openapi3Parser
         self["x-#{value}"]
       end
 
+      # @param [Any]  other
+      #
+      # @return [Boolean]
+      def ==(other)
+        other.instance_of?(self.class) &&
+          node_context.same_data_and_source?(other.node_context)
+      end
+
       # Iterates through the data of this node, used by Enumerable
       #
       # @return [Object]
@@ -55,6 +63,14 @@ module Openapi3Parser
         Placeholder.each(node_data, &block)
       end
 
+      # Provide an array of values for this object, a partner to the #keys
+      # method
+      #
+      # @return [Array]
+      def values
+        map(&:last)
+      end
+
       # Used to access a node relative to this node
       # @param  [Source::Pointer, ::Array, ::String] pointer_like
       # @return anything

data/lib/openapi3_parser/node/object.rb

@@ -48,6 +48,14 @@ module Openapi3Parser
         self["x-#{value}"]
       end
 
+      # @param [Any]  other
+      #
+      # @return [Boolean]
+      def ==(other)
+        other.instance_of?(self.class) &&
+          node_context.same_data_and_source?(other.node_context)
+      end
+
       # Iterates through the data of this node, used by Enumerable
       #
       # @return [Object]
@@ -55,11 +63,20 @@ module Openapi3Parser
         Placeholder.each(node_data, &block)
       end
 
+      # Provide an array of values for this object, a partner to the #keys
+      # method
+      #
+      # @return [Array]
+      def values
+        map(&:last)
+      end
+
       # Used to render fields that can be in markdown syntax into HTML
       # @param  [String, nil] value
       # @return [String, nil]
       def render_markdown(value)
         return if value.nil?
+
         Markdown.to_html(value)
       end
 

data/lib/openapi3_parser/node/operation.rb

@@ -70,6 +70,14 @@ module Openapi3Parser
       def servers
         self["servers"]
       end
+
+      # Whether this object uses it's own defined servers instead of falling
+      # back to the path items' ones.
+      #
+      # @return [Boolean]
+      def alternative_servers?
+        servers != node_context.parent_node.servers
+      end
     end
   end
 end