Add output of warnings to Kernel#warn

This sends warnings for a document to Kernel#warn so they are output for
a user. A document can be created with emit_warnings: false as a means
to suppress these.

Previously we only used warnings as an attribute of a document which
could be accessed which meant they were quite hidden. This was based on
the expectation that users are opening schemas they don't know about and
thus a warning isn't helpful. However I now think for most people they
are working with a schema in their codebase and thus it is better to be
more explicit.

Author: kevindew

lib/openapi3_parser.rb

@@ -7,32 +7,44 @@ module Openapi3Parser
   # For a variety of inputs this will construct an OpenAPI document. For a
   # String/File input it will try to determine if the input is JSON or YAML.
   #
-  # @param  [String, Hash, File]  input Source for the OpenAPI document
+  # @param  [String, Hash, File]  input           Source for the OpenAPI document
+  # @param [Boolean]              emit_warnings   Whether to call Kernel.warn when
+  #                                               warnings are output, best set to
+  #                                               false when parsing specification
+  #                                               files you've not authored
   #
   # @return [Document]
-  def self.load(input)
-    Document.new(SourceInput::Raw.new(input))
+  def self.load(input, emit_warnings: true)
+    Document.new(SourceInput::Raw.new(input), emit_warnings:)
   end
 
   # For a given string filename this will read the file and parse it as an
   # OpenAPI document. It will try detect automatically whether the contents
   # are JSON or YAML.
   #
-  # @param  [String]  path  Filename of the OpenAPI document
+  # @param  [String]  path            Filename of the OpenAPI document
+  # @param [Boolean]  emit_warnings   Whether to call Kernel.warn when
+  #                                   warnings are output, best set to
+  #                                   false when parsing specification
+  #                                   files you've not authored
   #
   # @return [Document]
-  def self.load_file(path)
-    Document.new(SourceInput::File.new(path))
+  def self.load_file(path, emit_warnings: true)
+    Document.new(SourceInput::File.new(path), emit_warnings:)
   end
 
   # For a given string URL this will request the resource and parse it as an
   # OpenAPI document. It will try detect automatically whether the contents
   # are JSON or YAML.
   #
-  # @param  [String]  url URL of the OpenAPI document
+  # @param  [String]  url             URL of the OpenAPI document
+  # @param [Boolean]  emit_warnings   Whether to call Kernel.warn when
+  #                                   warnings are output, best set to
+  #                                   false when parsing specification
+  #                                   files you've not authored
   #
   # @return [Document]
-  def self.load_url(url)
-    Document.new(SourceInput::Url.new(url.to_s))
+  def self.load_url(url, emit_warnings: true)
+    Document.new(SourceInput::Url.new(url.to_s), emit_warnings:)
   end
 end

lib/openapi3_parser/document.rb

@@ -9,11 +9,12 @@ module Openapi3Parser
   # @attr_reader  [OpenapiVersion]  openapi_version
   # @attr_reader  [Source]          root_source
   # @attr_reader  [Array<String>]   warnings
+  # @attr_reader  [Boolean]         emit_warnings
   class Document
     extend Forwardable
     include Enumerable
 
-    attr_reader :openapi_version, :root_source, :warnings
+    attr_reader :openapi_version, :root_source, :warnings, :emit_warnings
 
     # A collection of the openapi versions that are supported
     SUPPORTED_OPENAPI_VERSIONS = %w[3.0 3.1].freeze
@@ -78,10 +79,15 @@ class Document
                    :security, :tags, :external_docs, :extension, :[], :each,
                    :keys
 
-    # @param [SourceInput] source_input
-    def initialize(source_input)
+    # @param [SourceInput]  source_input
+    # @param [Boolean]      emit_warnings   Whether to call Kernel.warn when
+    #                                       warnings are output, best set to
+    #                                       false when parsing specification
+    #                                       files you've not authored
+    def initialize(source_input, emit_warnings: true)
       @reference_registry = ReferenceRegistry.new
       @root_source = Source.new(source_input, self, reference_registry)
+      @emit_warnings = emit_warnings
       @warnings = []
       @openapi_version = determine_openapi_version(root_source.data["openapi"])
       @build_in_progress = false
@@ -169,6 +175,7 @@ def look_up_pointer(pointer, relative_pointer, subject)
     end
 
     def add_warning(text)
+      warn("Warning: #{text}") if emit_warnings
       @warnings << text
     end
 
@@ -192,12 +199,12 @@ def determine_openapi_version(version)
       if version
         add_warning(
           "Unsupported OpenAPI version (#{version}), treating as a " \
-          "#{DEFAULT_OPENAPI_VERSION} document"
+          "#{DEFAULT_OPENAPI_VERSION} document."
         )
       else
         add_warning(
           "Unspecified OpenAPI version, treating as a " \
-          "#{DEFAULT_OPENAPI_VERSION} document"
+          "#{DEFAULT_OPENAPI_VERSION} document."
         )
       end
 

spec/lib/openapi3_parser/document/reference_registry_spec.rb

@@ -3,7 +3,7 @@
 RSpec.describe Openapi3Parser::Document::ReferenceRegistry do
   describe "#register" do
     let(:source_location) do
-      create_source_location({ contact: { name: "John Smith" } },
+      create_source_location({ openapi: "3.0.0", contact: { name: "John Smith" } },
                              pointer_segments: %w[contact])
     end
 
@@ -64,7 +64,7 @@
   describe "#factory" do
     let(:object_type) { "Openapi3Parser::NodeFactory::Contact" }
     let(:source_location) do
-      create_source_location({ contact: { name: "John Smith" } },
+      create_source_location({ openapi: "3.0.0", contact: { name: "John Smith" } },
                              pointer_segments: %w[contact])
     end
 

spec/lib/openapi3_parser/document_spec.rb

@@ -35,37 +35,48 @@ def raw_source_input(data)
     end
 
     context "when no OpenAPI version is provided" do
-      let(:instance) do
-        described_class.new(
-          raw_source_input(source_data.merge("openapi" => nil))
-        )
-      end
+      let(:input) { raw_source_input(source_data.merge("openapi" => nil)) }
 
       it "treats the version as the default for the library" do
-        expect(instance.openapi_version)
-          .to eq(Openapi3Parser::Document::DEFAULT_OPENAPI_VERSION)
+        instance = nil
+        expect { instance = described_class.new(input) }.to output.to_stderr
+        expect(instance.openapi_version).to eq(Openapi3Parser::Document::DEFAULT_OPENAPI_VERSION)
       end
 
       it "has a warning" do
-        expect(instance.warnings).to include(/Unspecified OpenAPI version/)
+        instance = nil
+        warning = /Unspecified OpenAPI version/
+        expect { instance = described_class.new(input) }
+          .to output(warning).to_stderr
+        expect(instance.warnings).to include(warning)
+      end
+
+      it "doesn't output to stderr when emit_warnings is false" do
+        expect { described_class.new(input, emit_warnings: false) }
+          .not_to output.to_stderr
       end
     end
 
     context "when an unsupported OpenAPI version is provided" do
-      let(:instance) do
-        described_class.new(
-          raw_source_input(source_data.merge("openapi" => "2.0.0"))
-        )
-      end
+      let(:input) { raw_source_input(source_data.merge("openapi" => "2.0.0")) }
 
       it "treats the version as the default for the library" do
-        expect(instance.openapi_version)
-          .to eq(Openapi3Parser::Document::DEFAULT_OPENAPI_VERSION)
+        instance = nil
+        expect { instance = described_class.new(input) }.to output.to_stderr
+        expect(instance.openapi_version).to eq(Openapi3Parser::Document::DEFAULT_OPENAPI_VERSION)
       end
 
       it "has a warning" do
-        expect(instance.warnings)
-          .to include(/Unsupported OpenAPI version #{Regexp.escape('(2.0.0)')}/)
+        instance = nil
+        warning = /Unsupported OpenAPI version #{Regexp.escape('(2.0.0)')}/
+        expect { instance = described_class.new(input) }
+          .to output(warning).to_stderr
+        expect(instance.warnings).to include(warning)
+      end
+
+      it "doesn't output to stderr when emit_warnings is false" do
+        expect { described_class.new(input, emit_warnings: false) }
+          .not_to output.to_stderr
       end
     end
   end
@@ -131,7 +142,7 @@ def raw_source_input(data)
     end
 
     it "returns errors for invalid source data" do
-      instance = described_class.new(raw_source_input({}))
+      instance = described_class.new(raw_source_input({ "openapi" => "3.0.0" }))
       expect(instance.errors).not_to be_empty
     end
 

spec/lib/openapi3_parser/node/context_spec.rb

@@ -168,11 +168,11 @@
 
   describe "#==" do
     let(:document_location) do
-      create_source_location({}, pointer_segments: %w[field_a])
+      create_source_location({ "openapi" => "3.0.0" }, pointer_segments: %w[field_a])
     end
 
     let(:source_location) do
-      create_source_location({},
+      create_source_location({ "openapi" => "3.0.0" },
                              document: document_location.source.document,
                              pointer_segments: %w[ref_a])
     end
@@ -213,17 +213,17 @@
 
   describe "#same_data_inputs?" do
     let(:source_location) do
-      create_source_location({}, pointer_segments: %w[ref_a])
+      create_source_location({ openapi: "3.0.0" }, pointer_segments: %w[ref_a])
     end
 
     let(:document_location) do
-      create_source_location({},
+      create_source_location({ openapi: "3.0.0" },
                              document: source_location.source.document,
                              pointer_segments: %w[field_a])
     end
 
     let(:other_document_location) do
-      create_source_location({},
+      create_source_location({ openapi: "3.0.0" },
                              document: source_location.source.document,
                              pointer_segments: %w[field_b])
     end
@@ -305,7 +305,7 @@
     end
 
     it "returns nil when there isn't a parent (for example at root)" do
-      instance = create_node_context({}, document_input: {})
+      instance = create_node_context({}, document_input: { "openapi" => "3.0.0" })
       expect(instance.parent_node).to be_nil
     end
   end

spec/lib/openapi3_parser/node_factory/components_spec.rb

@@ -101,7 +101,8 @@
 
     let(:node_factory_context) do
       create_node_factory_context(input,
-                                  document_input: { "components" => input })
+                                  document_input: { "openapi" => "3.0.0",
+                                                    "components" => input })
     end
   end
 

spec/lib/openapi3_parser/node_factory/context_spec.rb

@@ -2,7 +2,7 @@
 
 RSpec.describe Openapi3Parser::NodeFactory::Context do
   describe ".root" do
-    let(:input) { {} }
+    let(:input) { { "openapi" => "3.0.0" } }
     let(:source) { create_source(input) }
 
     it "returns a context instance" do
@@ -21,7 +21,7 @@
   end
 
   describe ".next_field" do
-    let(:input) { { "key" => "value" } }
+    let(:input) { { "openapi" => "3.0.0", "key" => "value" } }
     let(:parent_context) do
       create_node_factory_context(input, document_input: input)
     end
@@ -48,7 +48,7 @@
   end
 
   describe ".resolved_reference" do
-    let(:input) { "data" }
+    let(:input) { { "openapi" => "3.0.0" } }
     let(:source_location) { create_source_location(input) }
 
     let(:reference_context) do
@@ -67,7 +67,7 @@
       instance = described_class.resolved_reference(
         reference_context, source_location:
       )
-      expect(instance.input).to eq "data"
+      expect(instance.input).to eq(input)
     end
 
     it "has the resolved reference location" do
@@ -88,7 +88,7 @@
 
   describe "#location_summary" do
     it "returns a string representation of the pointer segments" do
-      source_location = create_source_location({}, pointer_segments: %w[path to field])
+      source_location = create_source_location({ "openapi" => "3.0.0" }, pointer_segments: %w[path to field])
       instance = described_class.new({}, source_location:)
       expect(instance.location_summary).to eq "#/path/to/field"
     end

spec/lib/openapi3_parser/node_factory/fields/reference_spec.rb

@@ -9,7 +9,7 @@
       pointer_segments: %w[field $ref]
     )
   end
-  let(:document_input) { {} }
+  let(:document_input) { { "openapi" => "3.0.0" } }
 
   describe "#resolved_input" do
     it "raises an error because a reference itself isn't resolved" do
@@ -33,8 +33,8 @@
     let(:instance) { described_class.new(factory_context, factory_class) }
 
     context "when the reference can be resolved" do
-      let(:document_input) do
-        { "reference" => { "name" => "Joe" } }
+      before do
+        document_input["reference"] = { "name" => "joe" }
       end
 
       it "is valid" do
@@ -43,8 +43,8 @@
     end
 
     context "when the reference can't be resolved" do
-      let(:document_input) do
-        { "reference" => { "url" => "invalid url" } }
+      before do
+        document_input["reference"] = { "url" => "invalid url" }
       end
 
       it "is invalid" do

spec/lib/openapi3_parser/node_factory/media_type_spec.rb

@@ -34,6 +34,7 @@
 
     let(:document_input) do
       {
+        "openapi" => "3.0.0",
         "components" => {
           "schemas" => {
             "Pet" => {

spec/lib/openapi3_parser/node_factory/oauth_flows_spec.rb

@@ -12,6 +12,7 @@
 
     let(:document_input) do
       {
+        "openapi" => "3.0.0",
         "myReference" => {
           "authorizationUrl" => "https://example.com/api/oauth/dialog",
           "tokenUrl" => "https://example.com/api/oauth/token",