Forum Discussion

nate_ubiquisoft's avatar
nate_ubiquisoft
New Contributor
7 years ago

Possible bug in JSON generation when using reusable examples from components/examples

Per documentation at https://swagger.io/docs/specification/adding-examples/ I should be able to define examples of schema objects and use them in request/response bodies. When defining a request body content like so:

... 
content: 
    application/json: 
        schema: 
            $ref: "#/components/schemas/BidLineSummary" 
        examples: 
            objectExample: 
                $ref: "#/components/examples/BidLineSummaryCapExample" 
... 


The generated API shows no values from the referenced example, but does show the object model and it's field defaults.

Changing up the above to be:

... 
content: 
    application/json: 
        schema: 
            $ref: "#/components/schemas/BidLineSummary" 
        example: 
            BidLineSummaryCapExample: 
                $ref: "#/components/examples/BidLineSummaryCapExample" 
... 


(note example with 's' removed)
gives generated JSON like:

{ 
    "BidLineSummaryCapExample": { 
        "value": { 
            "id": "bb89c07f-0f1b-47a9-bcac-ff9ac4f44ee0", 
            "bidMonth": 11, 
            "bidYear": 2018, 
            "baseName": "mem11", 
            "seatPosition": "CAP", 
            "userEnteredPilotCount": 365, 
            "systemPilotCount": null, 
            "userEnteredPayOnlyPilotCount": 52, 
            "systemPayOnlyPilotCount": null, 
            "userEnteredRegularLineCount": 208, 
            "systemRegularLineCount": null, 
            "suggestedRegularLineCount": null, 
            "userEnteredReserveLineCount": 34, 
            "systemReserveLineCount": null, 
            "suggestedReserveLineCount": null, 
            "userEnteredSecondaryLineCount": 71, 
            "systemSecondaryLineCount": null, 
            "suggestedSecondaryLineCount": null 
        }, 
        "$$ref": "#/components/examples/BidLineSummaryCapExample" 
    } 
} 

Why is it returning the $ref definition after the object body? The JSON is entirely wrong as the correct output should be:

{ 
    "id": "bb89c07f-0f1b-47a9-bcac-ff9ac4f44ee0", 
    "bidMonth": 11, 
    "bidYear": 2018, 
    "baseName": "mem11", 
    "seatPosition": "CAP", 
    "userEnteredPilotCount": 365, 
    "systemPilotCount": null, 
    "userEnteredPayOnlyPilotCount": 52, 
    "systemPayOnlyPilotCount": null, 
    "userEnteredRegularLineCount": 208, 
    "systemRegularLineCount": null, 
    "suggestedRegularLineCount": null, 
    "userEnteredReserveLineCount": 34, 
    "systemReserveLineCount": null, 
    "suggestedReserveLineCount": null, 
    "userEnteredSecondaryLineCount": 71, 
    "systemSecondaryLineCount": null, 
    "suggestedSecondaryLineCount": null 
} 


Which is the same output generated when defining the exact same example directly within the request body like so:

requestBody: 
    content: 
        application/json: 
            schema: 
                $ref: '#/components/schemas/BidLineSummary' 
            example: 
                id: bb89c07f-0f1b-47a9-bcac-ff9ac4f44ee0 
                bidMonth: 11 
                bidYear: 2018 
                baseName: mem11 
                seatPosition: CAP 
                userEnteredPilotCount: 365 
                systemPilotCount: null 
                userEnteredPayOnlyPilotCount: 52 
                systemPayOnlyPilotCount: null 
                userEnteredRegularLineCount: 208 
                systemRegularLineCount: null 
                suggestedRegularLineCount: null 
                userEnteredReserveLineCount: 34 
                systemReserveLineCount: null 
                suggestedReserveLineCount: null 
                userEnteredSecondaryLineCount: 71 
                systemSecondaryLineCount: null 
                suggestedSecondaryLineCount: null 


It appears this is a bug with the JSON generation when using $ref to components/examples. Any help would be appreciated as we can workaround currently by defining all examples in the request/response bodies but it would be much more useful to be able to have reusable examples.

Thanks,
Nate Brandeburg

  • nate_ubiquisoft's avatar
    nate_ubiquisoft
    7 years ago

    UPDATE:

    Response from Support (Thanks Wesley!):

    I received an update from the dev team regarding this issue.
    It seems to be working as expected, somewhat.
    There's a difference between 'example' and 'examples'. 'example' can contain a single example value and cannot reference an external example. The value of 'example' will be taken as-is, and that's the result in the current API definition.
    'examples' can contain multiple named examples, and these examples can have references.

    To solve the issue, you would either change the 'example' to 'examples' and leave the rest as-is, or remove the name of the example under the 'example' and inline the value instead of referencing.
    The issue as of now however is that we currently support rendering of 'example' but not plural 'examples'. So, you will notice that using examples does not return correctly either.

    Adding the use of 'examples' is currently being track by our team. Currently I would advise you to keep defining the examples directly.

    Once again I apologize for any inconvenience.


    Seems that defining them per request/response body is the only way to produce valid JSON for client consumption until examples support is implemented.

  • Support is actively looking into this now, so I will follow-up with whatever resolution we come to here so others who run into this issue can resolve it. Great support from SmartBear Customer Care!

    • nate_ubiquisoft's avatar
      nate_ubiquisoft
      New Contributor

      UPDATE:

      Response from Support (Thanks Wesley!):

      I received an update from the dev team regarding this issue.
      It seems to be working as expected, somewhat.
      There's a difference between 'example' and 'examples'. 'example' can contain a single example value and cannot reference an external example. The value of 'example' will be taken as-is, and that's the result in the current API definition.
      'examples' can contain multiple named examples, and these examples can have references.

      To solve the issue, you would either change the 'example' to 'examples' and leave the rest as-is, or remove the name of the example under the 'example' and inline the value instead of referencing.
      The issue as of now however is that we currently support rendering of 'example' but not plural 'examples'. So, you will notice that using examples does not return correctly either.

      Adding the use of 'examples' is currently being track by our team. Currently I would advise you to keep defining the examples directly.

      Once again I apologize for any inconvenience.


      Seems that defining them per request/response body is the only way to produce valid JSON for client consumption until examples support is implemented.