CODEWITHSUNDEEP
openapi
rom1bl
rom1bl

Reputation: 153

How to use $ref in an example declaration in OpenAPI?

I'm using OpenAPI for a project.

I have a schema "campaign" and another schema "campaign_collection", that is just a collection of the first one (plus a few additional meta fields).

campaign_collection schema:

campaign_collection:
  allOf:
    - $ref: '#/components/schemas/meta_fields'
    - type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/campaign'
    - $ref: '#/components/schemas/collection_meta_fields'

This works just fine. But, when I'm using examples, I'd like to use my Campaign example inside my campaign_collection example, something like this:

campaign_collection example:

campaign_collection:
  value:
    # A few meta fields...
    items:
      - $ref: '#/components/examples/campaign'
    # A few more meta fields...

But, it doesn't work, it renders like this in Swagger UI:

{
  "items": [
    {
      "$ref": "#/components/examples/campaign"
    }
  ]
}

Can I use $ref to make a reference to another example inside an example? I'd like to keep my campaign collection example up to date with my campaign example, instead of doing it manually. Can I do that in OpenAPI? Is there another way?

Upvotes: 9

Views: 7460

Answers (2)

Kevin Dijkstra
Kevin Dijkstra

Reputation: 21

$ref: sadly does not work in example: or in examples.<example_name>.value:.

However I do feel it is very worth mentioning you can use YAML anchors (&) and references/aliases (*) or as the Swagger Docs call them, Reusable Enums. One downside to this over $ref is that it has to be located somewhere in the same file that it's being used in as far as I know, but it's better than nothing.

You can define and use them like this:

campaign: &reusable_campaign
  key1: value1
  key2: value2
  etc1: etc2

campaign_collection:
  value:
    a_meta_key: Hello
    items:
      - *reusable_campaign
    another_meta_key: World

Upvotes: 0

Helen
Helen

Reputation: 97962

Just like example (singular), the examples.<name>.value key does NOT support $ref. The entire example must be specified inline. The contents of the value key is taken and displayed as is.

There is no way to reference a part of an example.

Upvotes: 9

Related Questions