Forum Discussion

Neterium's avatar
Neterium
New Contributor
8 years ago

(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

  • RonRatovsky's avatar
    RonRatovsky
    Icon for Staff rankStaff
    8 years ago

    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.

     

  • HKosova's avatar
    HKosova
    Icon for Alumni rankAlumni
    8 years ago

    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.

  • Neterium's avatar
    Neterium
    New Contributor
    8 years ago

    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 ?