cancel
Showing results for 
Search instead for 
Did you mean: 

(OpenAPI v3) Can't add an external JSON example

Neterium
New Contributor

(OpenAPI v3) Can't add an external JSON example

Hi,

 

I'm trying to add an example in my OpenAPI spec. I checked the specification and docs, it should look like this if I'm right:

(I've hidden the IP intentionally)

 

The spec sample:

 

content:
  application/json:
    schema:
      $ref: "#components/schemas/object"
    examples:
      jsonObject:
        summary: A sample object
        externalValue: http://example.com/examples/object-example.json

 

My spec:

 

 

content: 
  application/json:
    schema:
      $ref: 'http://xxx.xxx.xxx.xxx/schemas/1.0/screen.request.json'
    examples: 
      jsonObject:
        summary: A simple example
        externalValue: http://xxx.xxx.xxx.xxx/schemas/1.0/screen.request.example1.json

 

 

The JSON sample is accessible (the URL is checked and working) and is valid.

 

I've tried with or without quotes around the URL without success. It keeps generating a sample from the schema :(.

 

Did I miss anything ?

 

Many thanks!

3 REPLIES 3
RonRatovsky
Moderator

Re: (OpenAPI v3) Can't add an external JSON example

Hello there!

 

Your API definition is valid, no worries. However, currently swagger-ui does not support rendering of external examples, nor multiple examples - but we're working on adding it.

 


Did my reply answer your question? Give Kudos or Accept it as a Solution to help others.↓↓↓↓↓
HKosova
Moderator

Re: (OpenAPI v3) Can't add an external JSON example

A couple of notes in addition to what Ron said:

 

1)

      $ref: "#components/schemas/object"

should be

      $ref: "#/components/schemas/object"

with a / after #.

 

2)

    schema:
      $ref: 'http://xxx.xxx.xxx.xxx/schemas/1.0/screen.request.json'

You probably know this, but just in case - the schema in screen.request.json is supposed to be an OpenAPI Schema object and not a JSON Schema. E.g. this schema should not have the $schema, $id and other JSON Schema properties not supported by OpenAPI.


Helen Kosova
SmartBear Documentation Team Lead
________________________
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️
Neterium
New Contributor

Re: (OpenAPI v3) Can't add an external JSON example

Many thanks! Looking forward to the updated version then :).

 

Yes, those external JSON files are OPENAPI schema objects, they are external so that I can use them to validate incoming requests as well. I suppose there's no workaround to copy/paste one into that yaml API definition ?

New Here?
Join us and watch the welcome video:
Announcements
Top Kudoed Authors