Support for enum mapping

[smeng9]

Describe the bug

Current gen-api-docs command does not support generating docs with enum mapping
The doc will fail to build eventually

Expected behavior

The docs should build successfully

Current behavior

With following schema

{
  "openapi": "3.1.0",
  "info": {
    "title": "Service API Document",
    "version": "0.1"
  },
  "tags": [],
  "paths": {
    "/deliver": {
      "post": {
        "summary": "deliver <POST>",
        "operationId": "deliver",
        "description": "",
        "tags": [],
        "parameters": [],
        "responses": {},
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeliverBody"
              }
            }
          }
        }
      }
    },
    "/read-sensors": {
      "get": {
        "summary": "read_sensors <GET>",
        "operationId": "readSensors",
        "description": "",
        "tags": [],
        "parameters": [],
        "responses": {}
      }
    }
  },
  "components": {
    "schemas": {
      "DeliverBody": {
        "additionalProperties": false,
        "properties": {
          "side": {
            "$ref": "#/components/schemas/ExecutionCommand"
          }
        },
        "required": [
          "side"
        ],
        "title": "DeliverBody",
        "type": "object"
      },
      "ExecutionCommand": {
        "oneOf": [
          {
            "const": 0,
            "title": "NO_COMMAND"
          },
          {
            "const": 1,
            "title": "DELIVER_LEFT"
          },
          {
            "const": 2,
            "title": "DELIVER_RIGHT"
          }
        ],
        "title": "ExecutionCommand",
        "type": "integer"
      }
    }
  }
}

It will build with an empty <SchemaTab>

         <div>
          <span
            className={"badge badge--info"}
          >
            oneOf
          </span><SchemaTabs>
            
          </SchemaTabs>
        </div>

Then the docs will fail to build

Possible solution

Support enum mapping.

Steps to reproduce

1. Replace the petstore.yaml file in the example https://github.com/PaloAltoNetworks/docusaurus-template-openapi-docs/blob/main/examples/petstore.yaml project
2. Run gen-api-docs and then build
3. Build will fail with Error: Docusaurus static site generation failed for 1 paths:
4. Check the output deliver.api.mdx file

Screenshots

Context

We need to build docs with enum support

Your Environment

• Version used: 3.0.0-beta.10
• Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3): [INFO] Docusaurus version: 3.2.1, Node version: v20.10.0
• Operating System and version (desktop or mobile): macOS Sonoma 14.2
• Link to your project:

[adam-pasabi]

We'd like to have support for enums / oneOf so I'm going to explore implementing this. Any hints or suggestions where to look are definitely appreciated 💖

[sserrata]

Hi @adam-pasabi, today we have limited support for OpenAPI 3.1. Furthermore, I am not certain that the const data type is supported by OpenAPI. I tested the snippet you provided using Redocly and it parses the const schemas as "any", which I believe they fall back to in the event that they encounter an unknown/unsupported schema type. Our plugin does not provide any fallback, hence why the schema ends up being empty.

Have you considered refactoring the oneOf schema into an actual enum?

[adam-pasabi]

@sserrata I didn't provide the snippet for this issue, but I thought we were running into the same issue as our openAPI was rendering with an error. On further inspection I realised our openAPI config could be improved and is now definitely valid. My example is:

components:
  schemas:
    Data:
      type: object
      properties:   
        ip_address:
          $ref: "#/components/schemas/ip_address"
    ip_address:
      oneOf:
        - $ref: '#/components/schemas/ipv4_address'
        - $ref: '#/components/schemas/ipv6_address'
    ipv4_address:
        type: string
        format: "ipv4"
        description: IP address in v4 format
        example: "127.0.0.1"
    ipv6_address:
        type: string
        format: "ipv6"
        description: IP address in v6 format
        example: "0:0:0:0:0:0:0:1"

This successfully renders, but doesn't show the description or format information, so I'll review it with the rest of my team and possibly submit a PR to improve upon that aspect.

[IanVS]

@sserrata const should indeed be supported, according to OAI/OpenAPI-Specification#1313 (comment).

I think the reason redocly doesn't support it is due to Redocly/redocly-cli#1547

[IanVS]

Hi, I see that redocly merged a change to fix this, and this issue is your only open v3.0.0 labelled issue. Maybe it could be re-tagged for investigation in an upcoming version?