Description
During the recent issue backlog tidying effort, I closed at least six issues by pointing to @gregsdennis's Using Dynamic References to Support Generic Types blog post:
- Ability to define generic wrapper around the output #519
- Message format 'wrappers' #555
- Common response/payload object but different data defined per API? #773
- How can I represent java Generic type in swagger.yml #957
- Is there a way to make the $ref even more reusable with placeholders? #1749
- Add support for templatedRef in Reference Object #2453
But there are several problems with pointing folks to this technique:
- It's not mentioned in the OAS spec, so many people, including code generation tool developers, are not aware of it
- It's not even mentioned in the JSON Schema spec as it wasn't how I was thinking about it when I wrote those sections
$dynamicAnchorand$dynamicRefare among the most likely features to be hiding in the asterisk on many tools' "Supports OAS 3.1*" claims (it's basically takendiscriminator's place as the keyword that is left until the end to even attempt)
We already have a large section on supporting polymorphic types. We should add a brief section on generic types, at least enough to make it clear what keywords can be used. We should definitely do this in 3.2.0, and maybe even 3.1.1 as it does not add any new requirements. In 3.2.0, I suppose we could add requirements to support the idiom but I'd settle for making people aware of it. If there's demand for it, tools will add support, but first folks have to know about it.
I don't think we need to go into a lot of detail on how it works. That can be offloaded to the Learn site.