oneOf at root of schema generates empty <SchemaTabs> resulting in <Tabs> error

[billycrid]

Describe the bug

Given the following dependencies

"@docusaurus/core": "3.4.0",
"@docusaurus/preset-classic": "3.4.0",
"docusaurus-plugin-openapi-docs": "3.0.1",
"docusaurus-theme-openapi-docs": "3.0.1",

And with an openapi.yaml configuration of:

openapi: 3.0.0

info:
  title: some API
  description: some API
  version: "1"

servers:
  - url: /some-root

paths:

  # Some API
  /some-api:

    post:
      summary: some data
      requestBody:
        description: data
        required: true
        content: 
          application/json:
            schema:
              $ref: "#/components/schemas/someRequest"

      responses:
        '401':
          $ref: "#/components/responses/Unauthorized"
      security:
        - jwt: []

components:

  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Problem"

  schemas:
    Problem:
      type: object
      description: https://datatracker.ietf.org/doc/html/draft-ietf-appsawg-http-problem-00
      properties:
        type:
          type: string
          description: this is never actually used
          example: None
      required: ["type"]

    someRequest:
      type: object
      properties:
        operation:
          type: string
          enum: [something]
          default: something
          example: something
        module:
          type: string
          enum: [test]
          example: test
        file:
          type: string
          pattern: '^[$]{prefix}/(test)/.*[.](parquet|json)$'
          description: filename
          example: '${prefix}/test/something/foobar.json'
        query:
          description: some query
          type: object
          properties:
            id:
              type: string
              example: 'some id'
          required: [method, path]
      oneOf:
        - required: [query, file]
      additionalProperties: false

After running npm run gen-api-docs on this file, the output will compile correctly. However, after then running npm run build, the process will error with:

.....
[cause]: Error: Docusaurus static site generation failed for 1 paths:
  - "/ui-docs/docs/api/example/some-data"
.....
[cause]: Error: Docusaurus error: the <Tabs> component requires at least one <TabItem> children component
              at getInitialStateValue (server.bundle.js:64946:1059)

Looking at the outputted files i can see its rendered a <SchemaTabs></SchemaTabs - manually removing this the passes the build. But i feel this should either not be generated by the openapi-docs library or it should be generated with at least one tab to ensure it doesn't fail.

Expected behavior

gen-api-docs should either not generate SchemaTabs that are empty, or should add at least one item into it so it doesn't impact the build.

Current behavior

gen-api-docs generates empty SchemaTabs, thus blocking the build process.

Possible solution

gen-api-docs should either not generate SchemaTabs that are empty, or should add at least one item into it so it doesn't impact the build.

Steps to reproduce

provided above

Your Environment

[INFO] Docusaurus version: 3.4.0 Node version: v20.15.1

[sserrata]

Hi @billycrid, I believe that oneOf requires at least one schema to be defined for it to be valid. In your example, I only see the required property which isn't a schema. when I provide a valid schema it works as expected.

[billycrid]

Yeah fair point @sserrata - question though, is there anyway to handle invalid schemas then? Maybe throw an error during generate phase rather than build phase? Or least have some sort of catching for scenarios that could end up rendering Tabs without any TabItems?

[sserrata]

Hi @billycrid, although the plugin does perform some safety/type checking while parsing, it's not a full blown OpenAPI linter. That said, we could potentially try to catch/handle scenarios where <SchemaTabs> would have no children

FWIW, I use the spectral extension in vscode for linting but your case appears to go undetected since the use of required satisfies the linter rule which appears to only look for an array value, not necessarily a schema or schemas.