PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs
Response type array of oneOf or anyOf not displaying Example (From Schema) properly
Nobody has claimed this yet.
- 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.
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
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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