Allow customising the RefStrategy used by JsonSchemaConverter/OpenApiConverter

[Xtansia]

While working on the Smithy specifications for OpenSearch we've come across a need to tweak how and when $refs are introduced into the OpenAPI schema we generate from Smithy. This directly maps onto modifying the RefStrategy used by JsonSchemaConverter so that we can customise when certain types are inlined versus not and also how the schema/ref is named.

Currently the RefStrategy is hard-coded to RefStrategy::createDefaultStrategy, so I propose allowing this to be configured in some manner to use a custom implementation.

[mtdowling]

Can you describe what kinds of customizations you'd need from the RefStrategy? Assuming the changes aren't super niche, ideally we can add more high-level options to the plugin rather than directly allow customizing how refs are created. That'll help keep the converter maintainable while also making it easier for people to customize its behavior if necessary.

[Xtansia]

Our first use case is stopping specific schemas from being inlined that are currently always inlined (i.e. primitives & collections). This one I can see being implemented as a true feature using a marker trait that allows opting in or out of inlining, as it then becomes "free" to allow non-inlined types to be inlined (i.e. structures): @smithy.openapi#inline("never" | "always").

The second use case is to essentially insert a subsection of the namespace into the $ref path, e.g. OpenSearch.nodes._common#NodeResponseBase would become #/components/schemas/nodes._common:NodeResponseBase. This is the ask that I felt was far too niche to turn into a general feature, hence my framing this as allowing replacing the implementation of RefStrategy. This could also be done via trait or something, but annotating every single schema would be onerous.

[haydenbaker]

Archiving request as not planned. We will re-open this ticket if we find additional users who need this custom behavior.