From 4e8bfcf8d3ead0e6f4f377954566c6542ef22a5f Mon Sep 17 00:00:00 2001
From: John Gresty <john.gresty@snyk.io>
Date: Mon, 22 Jan 2024 21:35:52 +0000
Subject: [PATCH] fix: prevent similar components from being overwritten

When collating schemas from multiple services, it is very likely that
components with the same name will be defined in several places. We use
a comparison function to detect when this is the case and inline
components if they have already been declared.

This comparison function however ignored fields meant for documenting
fields. Which is fine when it was written as the only concern was
generating openapi specs inner service to validate requests. However now
we are using the collated specs to generate documentation, this
behaviour is very surprising. Especially when the description is
context sensitive.

This will increase the size of our specs slightly, it should not be that
significant. It will require us to recompile our existing specs to fix
the broken versions.
---
 collator.go                                              | 6 +-----
 collator_test.go                                         | 4 ++++
 .../conflict-components/_examples/2021-06-01/spec.yaml   | 9 +++++++++
 .../conflict-components/projects/2021-06-04/spec.yaml    | 8 ++++++++
 4 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/collator.go b/collator.go
index c2d9c59c..8fe86359 100644
--- a/collator.go
+++ b/collator.go
@@ -244,11 +244,7 @@ var cmpComponents = cmp.Options{
 	// Refs themselves can mutate during relocation, so they are excluded from
 	// content comparison.
 	cmp.FilterPath(func(p cmp.Path) bool {
-		switch p.Last().String() {
-		case ".Ref", ".Description", ".Example", ".Summary":
-			return true
-		}
-		return false
+		return p.Last().String() == ".Ref"
 	}, cmp.Ignore()),
 }
 
diff --git a/collator_test.go b/collator_test.go
index 36312e1a..f70e2951 100644
--- a/collator_test.go
+++ b/collator_test.go
@@ -96,6 +96,10 @@ func TestCollator(t *testing.T) {
 		"\"Requested API version\",\"pattern\":\"^(wip|work-in-progress|experimental|beta|((([0-9]{4})-([0-1][0-9]))"+
 		"-((3[01])|(0[1-9])|([12][0-9]))(~(wip|work-in-progress|experimental|beta))?))$\",\"type\":\"string\"}}\n", qt.JSONEquals, exampleParameterRef.Value)
 
+	projectConflictRef := result.Paths["/orgs/{orgId}/projects"].Get.Parameters[6]
+	exampleConflictRef := result.Paths["/examples/hello-world/{id}"].Get.Parameters[3]
+	c.Assert(projectConflictRef.Ref, qt.Not(qt.Equals), exampleConflictRef.Ref)
+
 	projectResp400Ref := result.Paths["/orgs/{orgId}/projects"].Get.Responses["400"]
 	c.Assert(projectResp400Ref.Ref, qt.Equals, "#/components/responses/400")
 	exampleResp400Ref := result.Paths["/examples/hello-world/{id}"].Get.Responses["400"]
diff --git a/testdata/conflict-components/_examples/2021-06-01/spec.yaml b/testdata/conflict-components/_examples/2021-06-01/spec.yaml
index b21bd215..3e2ba94d 100644
--- a/testdata/conflict-components/_examples/2021-06-01/spec.yaml
+++ b/testdata/conflict-components/_examples/2021-06-01/spec.yaml
@@ -20,6 +20,7 @@ paths:
           required: true
           schema:
             type: string
+        - $ref: '#/components/parameters/Conflict'
       responses:
         '400': { $ref: 'https://raw.githubusercontent.com/snyk/sweater-comb/v1.2.2/components/responses/400.yaml#/400' }
         '401': { $ref: 'https://raw.githubusercontent.com/snyk/sweater-comb/v1.2.2/components/responses/401.yaml#/401' }
@@ -43,6 +44,14 @@ paths:
                 additionalProperties: false
 
 components:
+  parameters:
+    Conflict:
+      name: conflict
+      in: query
+      required: true
+      description: Initial conflict description
+      schema:
+        type: string
   schemas:
     HelloWorld:
       type: object
diff --git a/testdata/conflict-components/projects/2021-06-04/spec.yaml b/testdata/conflict-components/projects/2021-06-04/spec.yaml
index 43523ae2..3eb9a076 100644
--- a/testdata/conflict-components/projects/2021-06-04/spec.yaml
+++ b/testdata/conflict-components/projects/2021-06-04/spec.yaml
@@ -17,6 +17,13 @@ components:
       description: The requested version of the endpoint to process the request
       schema:
         type: number
+    Conflict:
+      name: conflict
+      in: query
+      required: true
+      description: Different conflict description
+      schema:
+        type: string
   schemas:
     JsonApi:
       type: object
@@ -78,6 +85,7 @@ paths:
                 type: array
                 items:
                   type: string
+        - $ref: '#/components/parameters/Conflict'
       responses:
         '400': { $ref: '../../../resources/schemas/responses/400.yaml#/400' }
         '401': { $ref: 'https://raw.githubusercontent.com/snyk/sweater-comb/v1.2.2/components/responses/401.yaml#/401' }