Using x-example to control the examples displayed in the Developer Portal

OpenAPI does not support the use of example attributes on parameters, only on request and response objects and their properties. To allow API Developers to be able to control the examples displayed in the portal you can use x-example in OpenAPI parameters.

In this example, you cannot use example as it isn't supported by the OpenAPI spec, but you can use x-example.

 - name: city
   in: query
   required: false
   type: string
   maxLength: 50
   description: "Location"
   x-example: "New York"

An example attribute is honored where set and allowed by the spec. If example is not found, default is honored where set and allowed by the spec. An x-example attribute is honored if found, if not found, a random example to match the schema is generated.

If the spec allows you to use example, then you should use it in preference to x-example.