Need a way to express contextual examples with $refs

[cmars]

OpenAPI has a fundamental limitation with examples and $refs. You can put examples in referenced types, but if that type is something really generic like a JSON API link or our stripped-down relationship type, the example isn't going to be very relevant to the resource that you're reading about.

OpenAPI 3.1.0 took a step in the right direction, allowing summary: and description: to be used with $ref:.

Proposal: x-snyk-ref-example

Until OpenAPI catches up, proposing an extension x-snyk-ref-example that provides this capability. An extension is used so that it is clear and explicit that this is not yet standard OpenAPI behavior. It also gives us a clear way to ignore or adapt OpenAPI lint rules that might otherwise fail on it.

Example:

type: object
properties:
  links:
    $ref: "#/components/schemas/Links"
    x-snyk-ref-example:
      self:
        href: /what/an/actual/path/to/one/of/these/looks/like

[cmars]

Related:

• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#referenceObject
• Discussion about it in Description is not allowed for elements containing $ref OAI/OpenAPI-Specification#1514

[cmars]

A better alternative to consider is requiring sub-typed links to be used in resources, which would then have actually-relevant examples. Then we don't need a custom extension.