PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs

Support for anyOf/minProperties for required schema properties.

Open
#976 3 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Describe the bug

Given the following schema the generated page does not properly render and instead gives an error:

Docusaurus error: the <Tabs> component requires at least one <TabItem> children component
post:
  tags:
  - Suggested Entitlement Description
  operationId: submitSedBatchRequest
  summary: Submit Sed Batch Request
  description: 'Submit Sed Batch Request.

    Request body has one of the following:
      - a list of entitlement Ids
      - a list of SED Ids
    that user wants to have description generated by LLM. 
    API responses with batchId that groups Ids together'
  requestBody:
    description: Sed Batch Request
    content:
      application/json:
        schema:
          description: Sed Batch Request
          type: object
          anyOf:
            - required: [entitlements]
            - required: [seds]
          properties:
            entitlements:
              description: list of entitlement ids
              type: array
              items:
                type: string
                example: 016629d1-1d25-463f-97f3-c6686846650
            seds:
              description: list of sed ids
              type: array
              items:
                type: string
                example: 016629d1-1d25-463f-97f3-c6686846650

Expected behavior

Request body should display and show that you must specific either an array of entitlements or an array of sed ids.

Current behavior

I receive the error above, I believe this is because the plugin is not accounting for this use-case in open api specification.

Possible solution

Steps to reproduce

Create a schema with the use of anyOf property to denote that you must include either property.

Screenshots

Context

Your Environment

  • Version used:
  • Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3): Node v20.9.0
  • Operating System and version (desktop or mobile): MacOS Sonoma 14.7
  • Link to your project:

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

Start by reproducing the issue with the provided OpenAPI YAML and inspect the schema-rendering path that produces the Docusaurus Tabs error. Support the anyOf required-property case, including minProperties if relevant; done means the page renders and communicates the either/or requirement without the no-TabItem error.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.