Multiple examples for object properties swagger

Question

I am trying to add multiple examples for an Object property. The Swagger-Ui and Editor version that I am using are

'{"swaggerEditor":"3.6.31/g10642b3c-dirty","swaggerUi":{"version":"3.23.0","gitRevision":"g23d7260f","gitDirty":true,"buildTimestamp":"Sat, 29 Jun 2019 19:42:59 GMT","machine":"jenins-swagger-oss"}}'

Based on OpenAPI doc, this version of swagger UI and editor have support for multiple examples but I still see this error:

Structural error at components.schemas.MainObject.allOf.3.properties.partitionProperty
should NOT have additional properties
additionalProperty: examples
Jump to line 3016

This is how I have added the examples in the property:

    MainObject:
      allOf:
      - $ref: '#/components/schemas/MainObjectLite'
      - type: object
        description: foobar.
        readOnly: true
        required:
          - fooRequired
        properties:
         fooRequired:
            type: string
            description: system only field used for table data indexing
         partitionProperty:
            type: string
            description: foobar
            examples:
              sampleExample:
                value: 2016-03-04T03:00:00
                summary: sample partition

Lientery

Answer 1

OpenAPI 3.0

Multiple examples are only supported at the media type level and are not supported inside schemas. Schemas and properties can only have a single example, e.g.

partitionProperty:
  type: string
  example: '2016-03-04T03:00:00'

In other words, this won't work:

MainObject:
  type: object
  properties:
    ..
  examples:  # <--- Won't work
    minimal:
      summary: Minimal example
      value:
        foo: bar
    full:
      summary: Example with all properties
      value:
        foo: bar
        baz: xyzzy

If you want multiple examples, you need to use request examples or response examples instead:

requestBody:
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/MainObject'
      examples:
        minimal:
          summary: Minimal example
          value:
            foo: bar
        full:
          summary: Example with all properties
          value:
            foo: bar
            baz: xyzzy

OpenAPI 3.1

OAS 3.1 uses a newer version of JSON Schema which supports multiple examples in schemas and properties. Unlike media type examples which is a map of named Example Objects, schema-level and property-level examples is a plain list of example values.

MyObject:
  type: object
  properties:
    prop1:
      type: string
      # Property-level examples
      examples:
        - foo
        - bar
    prop2:
      type: integer

  # Object-level examples
  examples:
    - prop1: hello
      prop2: 5
    - prop1: world
      prop2: 0

Cataplasm

openapis.org/blog/2021/02/16/… Here is an example – Kesha

Answer 2

If you are stuck on OpenAPI v3.0.x and need (strongly desire) multiple examples, here is a hackish way to provide them within the schemas section (Note single quotes outside and double quotes inside):

common_phone:
  type: string
  maxLength: 14
  minLength: 1
  example: "'[phone]' or '614.555.1212' or '614-555-1212' or '6145551212'"

Quinquennium