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.

Author: jgresty

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()),
 }
 

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"]

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

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' }