Allow 3.1 references to have summary and description

In OpenAPI 3.1 references can have summary and description metadata for
nodes that support those fields. They operate in a cascading pattern
where each reference can overwrite the previous ones.

Author: kevindew

TODO.md

@@ -50,7 +50,7 @@ For OpenAPI 3.1
 - [x] Support summary field on Info node
 - [ ] Create a maxi OpenAPI 3.1 integration test to collate all the known changes
 - [ ] jsonSchemaDialect should default to OAS one
-- [ ] Allow summary and description in Reference objects
+- [x] Allow summary and description in Reference objects
 - [ ] Add identifier to License node, make mutually exclusive with URL
 - [ ] ServerVariable enum must not be empty
 - [ ] Add pathItems to components

lib/openapi3_parser/node_factory/reference.rb

@@ -9,6 +9,12 @@ class Reference < NodeFactory::Object
       include Referenceable
 
       field "$ref", input_type: String, required: true, factory: :ref_factory
+      field "summary",
+            input_type: String,
+            allowed: ->(context) { context.openapi_version >= "3.1" }
+      field "description",
+            input_type: String,
+            allowed: ->(context) { context.openapi_version >= "3.1" }
 
       attr_reader :factory
 

spec/lib/openapi3_parser/node_factory/reference_spec.rb

@@ -120,4 +120,82 @@ def create_node(input)
       expect(instance.resolves?([instance.context.source_location])).to be false
     end
   end
+
+  describe "summary field" do
+    let(:factory) do
+      Openapi3Parser::NodeFactory::OptionalReference.new(
+        Openapi3Parser::NodeFactory::Contact
+      )
+    end
+
+    it "accepts a summary field for OpenAPI >= v3.1" do
+      factory_context = create_node_factory_context(
+        {
+          "$ref" => "#/item",
+          "summary" => "summary contents"
+        },
+        document_input: {
+          "openapi" => "3.1.0",
+          "item" => {}
+        }
+      )
+      expect(described_class.new(factory_context, factory)).to be_valid
+    end
+
+    it "rejects a summary field for OpenAPI < v3.1" do
+      factory_context = create_node_factory_context(
+        {
+          "$ref" => "#/item",
+          "summary" => "summary contents"
+        },
+        document_input: {
+          "openapi" => "3.0.0",
+          "item" => {}
+        }
+      )
+      instance = described_class.new(factory_context, factory)
+
+      expect(instance).not_to be_valid
+      expect(instance).to have_validation_error("#/").with_message("Unexpected fields: summary")
+    end
+  end
+
+  describe "description field" do
+    let(:factory) do
+      Openapi3Parser::NodeFactory::OptionalReference.new(
+        Openapi3Parser::NodeFactory::Contact
+      )
+    end
+
+    it "accepts a description field for OpenAPI >= v3.1" do
+      factory_context = create_node_factory_context(
+        {
+          "$ref" => "#/item",
+          "description" => "description contents"
+        },
+        document_input: {
+          "openapi" => "3.1.0",
+          "item" => {}
+        }
+      )
+      expect(described_class.new(factory_context, factory)).to be_valid
+    end
+
+    it "rejects a description field for OpenAPI < v3.1" do
+      factory_context = create_node_factory_context(
+        {
+          "$ref" => "#/item",
+          "description" => "description contents"
+        },
+        document_input: {
+          "openapi" => "3.0.0",
+          "item" => {}
+        }
+      )
+      instance = described_class.new(factory_context, factory)
+
+      expect(instance).not_to be_valid
+      expect(instance).to have_validation_error("#/").with_message("Unexpected fields: description")
+    end
+  end
 end

spec/support/examples/v3.1/changes.yaml

@@ -8,6 +8,18 @@ info:
   #   identifier: Apache-2.0
 # jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base
 components:
+  examples:
+    FullExample:
+      summary: Original summary
+      description: Original description
+      value: anything
+    ReferencedExample:
+      summary: Referenced summary
+      description: Referenced Description
+      $ref: "#/components/examples/FullExample"
+    DoubleReferencedExample:
+      summary: Double referenced summary
+      $ref: "#/components/examples/ReferencedExample"
   schemas:
     BasicSchema:
       description: "My basic schema"