fix: Add OpenAPI 3.1 $ref overrides

[DanielOaks]

In OpenAPI 3.1 documents, you can include description and summary params alongside a $ref, and those fields will override any imported value from the $ref. This change adds the ability to accept those values.

I'm not sure how/whether to make this only apply to 'openapi 3.1' documents, but I've tried my best to include a usable spec to test this behaviour. Thanks!

Note: Specifically, I'm trying to solve this issue when I upload OAS 3.1.0 specs to my ReadMe reference section – here's an example of this description overriding in action in the uploaded spec but not being reflected on the site: https://doakstest.readme.io/reference/post-user

[erunion]

This seems good to me! I don't think we really need to worry about only applying this to OpenAPI 3.1 specs because this library is a bit more generalized.

[erunion]

Thanks again for this @DanielOaks. A new release of rdme has just been published to incorporate this (along with updates to @readme/openapi-parser and oas-normalize). This change will also be landing in our production deployment tomorrow morning.

[DanielOaks]

@erunion thanks for digging into this! I'm having some trouble getting this to work – since rdme just uses the bundle() function from here [1] [2] [3] the new normalization in this PR doesn't affect the spec that gets uploaded. rdme could maybe call .deref() after bundling the spec, but that wouldn't resolve it in specs that get uploaded via the web UI

Any chance you could give me a yell when this lands in the production env, if a backend change is what'll let this feature work? (sorry for being a pain, we have some stuff waiting on this on my end. good luck with the upcoming product update preview 🥳)

[erunion]

Ah rats, so we actually do dereference work in our frontend by calling OAS.dereference() in our OpenAPI tooling library oas. I updated every dependency in our production environment but this one. 😔

I'll get that together for tomorrows morning release.

[erunion]

@DanielOaks I just merged that work in so it'll be in tomorrows release! Here it is working:

We deploy usually before 12pm SF time so you should notice it sometime then tomorrow but let us/me know if you've still got troubles with it.

[DanielOaks]

Aha thanks very much mate! I appreciate it a lot 🙏 \o/