PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs

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

Open
#617 2 comments 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement roadmap
Dominant language
TypeScript
Stars
1.1k
Forks
315
Avg merge
7d 5h
Merged PRs (30d)
7

Description

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.
image

The Example (From Schema) produces this result:
image

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the Example (From Schema) output using the provided array response schemas with oneOf and anyOf items. Trace the example-generation entry point for response schemas, then verify that the generated array contains the first listed schema rather than empty objects.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.