Stabilize order of parameter objects and preserve objects with newer example

[exoego]

This is a spin-out from #57
After this PR, parameters array preserves the occurrence with newer value in example

Current implementation

It keeps the first occurrence of duplicated items with same name & in.
If user update an existing parameter in their rspec, a new parameter object with newer value in example fieldis added to parameters` array ... but is removed soon because it is not the first occurrence.
In other words, the occurrence with oldest example is kept forever.

Problems

"Preserving first occurrence" will cause a problem for some cases.

1. User changed the value format.

Let's say user changed the format of id from numeric (123) to ulid (01ARZ3NDEKTSV4RRFFQ69G5FAV).

• Base spec, [{ name: "id", in: "path", example: "123" }]
• After merge, [{ name: "id", in: "path", example: "123" }, { name: "id", in: "path", example:"01ARZ3NDEKTSV4RRFFQ69G5FAV" }]
• After deduplication, [{ name: "id", in: "path", example: "123" }]

😭 The preserved 123 is wrong about format.

2. rspec-openapi support another field of parameter object

Let's say rspec-openapi added description field in parameter object somehow.

• Base spec, [{ name: "id", in: "path", example: "123" }]
• After merge, [{ name: "id", in: "path", example: "123" }, { name: "id", in: "path", example:"123", description:"blah blah" }]
• After deduplication, [{ name: "id", in: "path", example: "123" }]

😭 description is not added.

Solution

1. Keep a last occurrence

Unfortunately, it brings unstable order.
Let's say we invokes /foo/123 and /foo/456 in rspec.

• 1st run
  • Base spec, [{ name: "id", in: "path", example: "123" }]
  • After merge, [{ name: "id", in: "path", example: "123" }, { name: "id", in: "path", example:"456" }]
  • After deduplication, [{ name: "id", in: "path", example: "456" }]
• 2nd run: (just rerun)
  • Base spec, [{ name: "id", in: "path", example: "456" }]
  • After merge, [{ name: "id", in: "path", example: "456" }, { name: "id", in: "path", example: "123" } ]
  • After cleanup, [{ name: "id", in: "path", example: "123" }]

😭 123 and 456 is oscillating for each run.

2. Introduces a timestamp marker to be used as sort key

I think it is better to introduce __marker: Timestamp field to parameters.
Then, merger sorts the parameters and preserves the duplicates with largest __marker, so the older occurrencenes will be removed.

This PR also sorts parameters by in and name before __marker, because sort_by is not "stable sort"

[exoego]

Hmm, all tests passed on my end 🤔

[exoego]

Note) 42 came from the updated test

[exoego]

@k0kubun Could you take a look 🙇

[k0kubun]

Sorry, I didn't read this when the CI was not passing and I didn't get a notification when it started to pass. I'll take a look.

[k0kubun]

The PR is now concise enough to make me understand how and why it's used. Thank you.

I have some suggestions here though:

• Can we insert them inside SchemaMerger instead of SchemaBuilder? This seems to be the concern for SchemaMerger and it feels like the current implementation scatters the implementation details to unrelated places. This PR should touch SchemaBuilder.
• Could we achieve the same thing by just always prepending new schema elements to the array in SchemaMerger and calling uniq! after that? It should give the same result as sorting based on __marker.

[exoego]

Can we insert them inside SchemaMerger instead of SchemaBuilder?

It makes sense. 6326392
And it turned out that __marker is not needed. 1128a0c

Could we achieve the same thing by just always prepending new schema elements to the array in SchemaMerger and calling uniq! after that?

Yes, sort! removed 2e88f76
Without sort!, diffs on the existing rails/doc/openapi.(json|yml) is bigger.

[k0kubun]

👍