cancel
Showing results for 
Search instead for 
Did you mean: 

Referencing Examples

me_slack
New Contributor

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

Screenshot 2021-04-17 at 16.01.16.pngScreenshot 2021-04-17 at 16.01.23.png

Any help would be appriciated

4 REPLIES 4
joejoyce
Staff

Re: Referencing Examples

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/

 

me_slack
New Contributor

Re: Referencing Examples

Hi @joejoyce 

As it's a nodejs app, I am using openapi-comment-parser to build the JSON, which uses a YAML file to store the details.

 

Then I render this JSON file via Redoc

 

The JSON lives here: https://api.juicyllama.com/docs/openapi.json

And the docs live: https://api.juicyllama.com/#tag/Webhook

 

Thanks for replying.

 

joejoyce
Staff

Re: Referencing Examples

Thanks for the extra info.

 

I did a quick test there by importing the JSON from here (https://api.juicyllama.com/docs/openapi.json) into SwaggerHub to see how it would be rendered by the documentation. The result looked like this:

joejoyce_0-1618923479836.png

Which looks to me like we are picking  up the reference and rendering it correctly. Have you tried rendering the JSON using Swagger UI instead of Redoc, as a test? Because SwaggerHub seems to think that the JSON is valid.

HKosova
Moderator

Re: Referencing Examples

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"
    }
  ]

Helen Kosova
SmartBear Documentation Team Lead
________________________
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️
New Here?
Join us and watch the welcome video:
Top Kudoed Authors