How to specify an example of two path template parts in OpenAPI / Swagger

user_4918250 0
Viewed 141

Given a path template with two parts such as:

paths:
 /blah/{fooPart}-stuff-{barPart}:
    parameters:
      - in: path
        name: fooPart 
        description: foo part of this matrix ID
        required: true
        schema:
          type: string
      - in: path
        name: barPart
        description: bar part of this matrix ID
        required: true
        schema:
          type: string

I'd like to provide an list of examples. Since the fooPart and the barPart are correlated, i'd like to have each example have the corrrelated data elements. I'd imagine putting it in the components

examples:
  Happy:
    summary: Happy path
    value:
      fooPart: red
      barPart: up
  Sad:
    summary: Sad path
    value:
      fooPart: up
      barPart: red

When i add the refs as an examples list to each parameter, like so

      - in: path
        name: fooPart 
        description: foo part of this matrix ID
        required: true
        schema:
          type: string
        examples:
          happy:
            $ref: "#/components/example/Happy"
          sad:
            $ref: "#/components/example/Sad"

the rendered display is ... adequate? Wrong? Not helpful? The examples aren't correlated and the array specified as value is presented in the box for each parameter, as seen here. I recognize, this is what i told it to do. Is there any way to bundle all the examples together? Or is my only option the one i will offer as an answer? Ugh.

swagger openapi
1 Answers

I'm assuming the only option is

examples:
  HappyFoo:
    summary: Happy path
    value: red
  HappyBar:
    summary: Happy path
    value:  up
  SadFoo:
    summary: Sad path
    value:  red
  SadBar:
    summary: Sad path
    value: red

With each parameter only including its own values like so:

    parameters:
      - in: path
        name: fooPart 
        description: foo part of this matrix ID
        required: true
        schema:
          type: string
        examples:
          Happy:
            $ref: "#/components/examples/HappyFoo"
          Sad:
            $ref: "#/components/examples/SadFoo"

The examples aren't correlated, but at least the value in the box is correct as seen here.

user_49182500
Related