Forum Discussion

HenrikHL's avatar
HenrikHL
Frequent Contributor
2 years ago

Autogenerated examples vs manually generated examples

Hi all,

We rely heavily on Domains and hense reuse objects a lot. It is fantastic that SwaggerHub autogenerates examples - this helps a lot.

Sometimes when reusing objects - the autogenerated examples do not make sense! Here is an example:

We have these 2 simple types (location and temperature) and 1 object combining the two (combined) :

 

components:
  schemas:
    location:
      type: string
      description: 'A place in the world'
      example: 'North Pole'
    temperature:
      type: number
      description: 'The temparature in degrees'
      example: 50
    combined:
      type: object
      allOf:
        - $ref: '#/components/schemas/location'
        - $ref: '#/components/schemas/temperature'

 

Displaying the example for combined:

 

{
  "location": "North Pole",
  "temperature": 50
}

 

In this case I would like to extend the example - I would normally do it like this:

 

components:
  schemas:
    combined:
      type: object
      allOf:
        - $ref: '#/components/schemas/location'
        - type: object
          properties:
            allOf:
              - $ref: '#/components/schemas/temperature'
              - example:
                location: 'North Pole'
                temperature: -20

 

This displays a more realistic example (-20 degrees on North Pole).

Problem here is when the combined object changes (for example removing the temperature field) - the example (because it is manually created) becomes invalid. If I forget to update the example also - then the specs are wrong.

Does anyone have a good solution for this? Is it possible at all to modify examples and have SwaggerHub monitor that the example is still valid?