Custom description for referenced component is sometimes ignored (caching issue in upstream parser?)

[IMSoP]

This is a bit hard to describe, and I believe the actual bug here is in an upstream dependency, but I'm not sure where exactly to look.

When using $ref in a schema, it's possible to include a description both in the shared component being referenced (e.g. describing a type), and in the property itself (e.g. describing its usage in context). The relevant specs leave it up to implementations what to do here: show both descriptions, or over-write one with the other.

The parser used in OpenAPI Explorer appears to prefer the "local" description, discarding the one from the shared reference. However, it sometimes fails to do so.

Playing around with an example, this appears to be some kind of caching bug: if you always supply a description when using a particular component, that description is displayed. However, if you have previously referenced the component without overwriting its description, further custom descriptions are ignored.

For an example, load this OpenAPI description file with OpenAPI Explorer, and observe:

• The top-level fields with custom descriptions display them
• nested-one-custom displays its custom description - that component has only been used with a custom description, so is not cached(?)
• nested-two-custom ignores the custom description - somehow the top-level two-default populated a cache(?)
• double-nested-three-custom ignores the custom description - because nested-three-default populated the cache(?)
• double-nested-four-custom ignores the custom description - because nested-four-default populated the cache(?)

[wparad]

Interesting. Had no idea there was a problem like that. The first step would be to dive into the spec parser, and see if the problem is the parsed spec is the issue or if the spec handling in this library is the problem.

Update the dependency we are using has a bug, we are working on pulling it out and replacing it.

[wparad]

This has been fixed in version 1.0 release og 1.0.496.

[wparad]

FYI @adamsussman, I saw your issue over in the RapiDoc repo. This repo is a fork of RapiDoc from pretty recently, and the issue regarding overwriting of descriptions has been fixed. Actually it was a change we made that enabled libraries such as the OpenAPI Explorer to support custom overrides. For the most part it is a drop in replacement for RapiDoc which gives you a lot of the same look and feel but has a number of these more annoying things fixed. It's not a simple 1:1 switch, but if you do find something not supported it would be great to let us know (hopefully those in a new issue ticket)

[adam-homeboost]

Thank you @wparad, will take a look!