2

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

1 Answer 1

0

It was an issue with Swagger UI.

Fixed in Swagger UI 4.5.0 and Swagger Editor 4.0.7.

1
  • 1
    Fixed in the Swagger-JS 3.8.14. release. Feb 2, 2022 at 15:18

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.