Response type array of oneOf or anyOf not displaying Example (From Schema) properly

[colin-mckibben-sp]

Describe the bug

A response of type array that uses the anyOf or oneOf discriminators to define the items will result in an incomplete Example (From Schema).

Expected behavior

The Example (From Schema) should display the first schema type defined in the oneOf or anyOf.

Current behavior

The Example (From Schema) is displayed as an array of two empty objects.

For example, in our API spec the get campaigns API has a response schema of type array of oneOf two schemas.

The Example (From Schema) produces this result:

We provide additional examples for slim and full campaign, which work as expected.

Possible solution

When a response schema is an array of oneOf or anyOf items, the docs generator should select the first item in the list to populate the Example (From Schema) so it is not empty. It is up to the owner of the API spec to provide additional examples if they want to show what a response for the other types in the oneOf or anyOf could be.

responses:
    '200':
      description: A list of campaign objects.
      content:
        application/json:
          schema:
            type: array
            items:
              oneOf:
                - $ref: '../schemas/SlimCampaign.yaml'
                - $ref: '../schemas/Campaign.yaml'
          examples:
            Slim Campaign:
              $ref: '../schemas/campaign/examples/SlimCampaigns.yaml'
            Full Campaign:
              $ref: '../schemas/campaign/examples/FullCampaigns.yaml'

Steps to reproduce

Link to an example of oneOf: https://developer.sailpoint.com/idn/api/v3/get-active-campaigns Link to example of anyOf: https://developer.sailpoint.com/idn/api/beta/list-accounts

Define a response to an endpoint with type array and items that are oneOf or anyOf more than one schema.

responses:
    '200':
      description: A list of campaign objects.
      content:
        application/json:
          schema:
            type: array
            items:
              oneOf:
                - $ref: '../schemas/SlimCampaign.yaml'
                - $ref: '../schemas/Campaign.yaml'
          examples:
            Slim Campaign:
              $ref: '../schemas/campaign/examples/SlimCampaigns.yaml'
            Full Campaign:
              $ref: '../schemas/campaign/examples/FullCampaigns.yaml'

Context

This is a fairly minor issue, but it does affect the consistency of our API examples. We strive to provide accurate examples for each response, but there doesn't seem to be any way to get the schema example to generate properly for this type of response. Having the docs generator default to the first value in the array of schemas will help keep the examples consistent and complete.

Your Environment

Currently using docusaurus 2.2.0 and docusaurus-plugin-openapi-docs 0.0.0-616

[kooyunmo]

+1

[sserrata]

Adding to roadmap with goal of generating polymorphic schemas using the first schema.