Forum Discussion

me_slack's avatar
me_slack
New Contributor
4 years ago

Referencing Examples

Hi Guys,

I am trying to understand how to reference examples, I have two example endpoints:

 

GET /badge -> {Badge}

GET /badges -> [Badges]

 

So I would like to use the same example but in the /badges render this inside an array object.

 

I have the following:

 

BadgeExample:
      value: {
        "badge_id": 1,
        "app_id": 1,
        "name": "Most Villains Captured",
        "app_json": null,
        "created_at": "2000-01-01 00:00:00",
        "updated_at": "2000-01-01 00:00:00"
      }
BadgesExample:
      value: [
          $ref: '#/components/examples/BadgeExample'
    ]

 

However when i render the reporting it is not picking up the reference



Any help would be appriciated

  • Hey me_slack. How are you rendering the reporting in those screenshots? Is that Swagger UI, or some other environment? 

     

    According to RFC3986, the $ref string value (JSON Reference) should contain a URI, which identifies the location of the JSON value you are referencing to. If the string value does not conform URI syntax rules, it causes an error during the resolving. Any members other than $ref in a JSON Reference object are ignored.

     

    You can find examples of references here: https://swagger.io/docs/specification/using-ref/

     

  • HKosova's avatar
    HKosova
    SmartBear Alumni (Retired)

    Hi me_slack,

     

    $ref is not supported inside example values, that is, inside the example and examples.<name>.value keywords. The entire value must be specified inline. So you need to change the BadgesExample array example to include the actual literal object:

    
    BadgesExample:
      value: [
        {
          "badge_id": 1,
          "app_id": 1,
          "name": "Most Villains Captured",
          "app_json": null,
          "created_at": "2000-01-01 00:00:00",
          "updated_at": "2000-01-01 00:00:00"
        }
      ]