Search code examples
swagger-uiopenapi

Why did a schema inherit examples of array items from its subschema?


OpenAPI 3.0.0, Swagger online editor.

I composed subschemas via the allOf discriminator and set the example field for a resulting schema. Swagger UI, however, didn't provide the example as-is.

The schema contained an array originating from the subschema. The array inherited example items from the subschema and extended the list with the examples from the schema.

Example

Let's say we have two schemas:

Cats:
  type: object
  properties:
    cats:
      type: array
      items:
        type: object
        properties:
          fluffiness:
            type: integer
          names:
            type: string
  example:
    cats:
      - fluffiness: 9
        names: "Felix"
      - fluffiness: 10
        names: "Neko"
        

FluffiestCats:
  allOf:
    - $ref: '#/components/schemas/Cats'
    - type: object
      properties:
        date:
          type: string
          format: "date"
  example:
    cats:
      - fluffiness: 10
        names: "Luna" 
      - fluffiness: 10
        names: "Meowie"
    date: "17-01-2021"

Responding to some request, the API retrieves the fluffiest cats, referencing #/components/schemas/FluffiestCats/. Swagger UI generates the following response example.

{
  "cats": [
    {
      "fluffiness": 9,
      "names": "Felix"
    },
    {
      "fluffiness": 10,
      "names": "Neko"
    },
    {
      "fluffiness": 10,
      "names": "Luna"
    },
    {
      "fluffiness": 10,
      "names": "Meowie"
    }
  ],
  "date": "17-01-2021"
}

Swagger UI takes two examples from the subschema example items. The provided example doesn't override the subschema example.

  1. Does this behaviour contradict the specification? According to the description, it seems the Schema Object's example field doesn't imply override, in contrast to the Parameter Object's example field.
  2. How can I override the subschema example? Or do I have to recreate the schema without using the allOf?

References

  1. How to reference array item examples in OpenAPI 3?
  2. OpenAPI 3.0.0 specification

Solution

  • It was an issue with Swagger UI.

    Fixed in Swagger UI 4.5.0 and Swagger Editor 4.0.7.