openapi

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?


Solution

  • 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.