Skip to content

Commit

Permalink
fix: prevent similar components from being overwritten
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
jgresty committed Jan 23, 2024
1 parent 93f01b0 commit 4e8bfcf
Show file tree
Hide file tree
Showing 4 changed files with 22 additions and 5 deletions.
6 changes: 1 addition & 5 deletions collator.go
Original file line number Diff line number Diff line change
Expand Up @@ -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()),
}

Expand Down
4 changes: 4 additions & 0 deletions collator_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand Down
9 changes: 9 additions & 0 deletions testdata/conflict-components/_examples/2021-06-01/spec.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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' }
Expand All @@ -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
Expand Down
8 changes: 8 additions & 0 deletions testdata/conflict-components/projects/2021-06-04/spec.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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' }
Expand Down

0 comments on commit 4e8bfcf

Please sign in to comment.