openapi 3.1 enum array gets generated as union instead of union array

[darkbasic]

openapi-typescript version

7.6.0

Node.js version

20.17.0

OS + version

Arch Linux

Description

openapi 3.1 json:

{
    "name": "metrics",
    "in": "query",
    "required": true,
    "schema": {
        "type": "array",
        "enum": [
            "product_requirements_mandatory_completed",
            "product_requirements_optional_completed",
            "product_requirements_total_completed"
        ],
        "items": {
            "type": "string"
        },
        "minItems": 1
    }
},

Generated typings:

export interface operations {
  'analytics.data': {
    parameters: {
      query: {
        metrics:
          | 'product_requirements_mandatory_completed'
          | 'product_requirements_optional_completed'
          | 'product_requirements_total_completed'

Expected:

export interface operations {
  'analytics.data': {
    parameters: {
      query: {
        metrics: Array<
          | 'product_requirements_mandatory_completed'
          | 'product_requirements_optional_completed'
          | 'product_requirements_total_completed'
        >

Reproduction

analytics.json:

{
    "openapi": "3.1.0",
    "info": {
        "title": "API Portal",
        "version": "1.0.0",
        "description": "This is the **Analytics API** description"
    },
    "paths": {
        "\/analytics\/data": {
            "get": {
                "operationId": "analytics.data",
                "tags": [
                    "Analytics"
                ],
                "parameters": [
                    {
                        "name": "metrics",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "array",
                            "enum": [
                                "product_requirements_mandatory_completed",
                                "product_requirements_optional_completed",
                                "product_requirements_total_completed"
                            ],
                            "items": {
                                "type": "string"
                            },
                            "minItems": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "`AnalyticsResponseResource`",
                        "content": {
                            "application\/json": {
                                "schema": {
                                    "$ref": "#\/components\/schemas\/AnalyticsResponseResource"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#\/components\/responses\/AuthorizationException"
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "http": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": ""
            }
        },
        "schemas": {
            "AnalyticsResponseDataResource": {
                "type": "object",
                "properties": {
                    "metricValues": {
                        "type": "array",
                        "items": {
                            "anyOf": [
                                {
                                    "type": "integer"
                                },
                                {
                                    "type": "number"
                                }
                            ]
                        }
                    }
                },
                "required": [
                    "metricValues"
                ],
                "title": "AnalyticsResponseDataResource"
            },
            "AnalyticsResponseResource": {
                "type": "object",
                "properties": {
                    "metricHeaders": {
                        "type": "string"
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#\/components\/schemas\/AnalyticsResponseDataResource"
                        }
                    }
                },
                "required": [
                    "metricHeaders",
                    "data"
                ],
                "title": "AnalyticsResponseResource"
            }
        },
        "responses": {
            "AuthorizationException": {
                "description": "Authorization error",
                "content": {
                    "application\/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "message": {
                                    "type": "string",
                                    "description": "Error overview."
                                }
                            },
                            "required": [
                                "message"
                            ]
                        }
                    }
                }
            }
        }
    }
}

npx openapi-typescript analytics.json -o analytics.ts

Expected result

Array<'product_requirements_mandatory_completed' | 'product_requirements_optional_completed'  | 'product_requirements_total_completed'>

Required

• My OpenAPI schema is valid and passes the Redocly validator (npx @redocly/cli@latest lint)

Extra

• I’m willing to open a PR (see CONTRIBUTING.md)

[phmasek]

I believe the JSON specification is incorrect. If you change the specification to this it seems to work:

{
  "name": "metrics",
  "in": "query",
  "required": true,
  "schema": {
    "type": "array",
    "items": {
      "type": "string",
      "enum": [
        "product_requirements_mandatory_completed",
        "product_requirements_optional_completed",
        "product_requirements_total_completed"
      ]
    },
    "minItems": 1
  }
}

Note how the enum is located within the items property.

[darkbasic]

@phmasek thanks, it does indeed work but at the same time the original syntax works as well with tools like Stoplight:

[duncanbeevers]

thanks, it does indeed work but at the same time the original syntax works as well with tools like Stoplight

I'll bring this up at the OpenAPI TDC. It seems pretty obviously broken to me and your tools should be yelling at you, but if the spec doesn't forbid it you're in the clear, and we may just have to clear this up in OpenAPI 3.2 or 3.3.

[duncanbeevers]

Conversing with the community, it seems like this is allowable, but undefined behavior. Whether the type or the enum wins is implementation-defined, and it seems like Stoplight allows the enum to trump the type: array.

Redocly offers a linting rule no-enum-type-mismatch which may help you prevent this kind of conflation.

[duncanbeevers]

@darkbasic You may want consider opening a ticket against Stoplight for this behavior. It's clear to me that this isn't an openapi-ts issue. Furthermore, I don't feel it's our purview to lint documents this way; rather, the generated types are an example of implementation-defined behavior in the face of invalid inputs.

I'm open to ideas about how to make it more obvious what is going on here. For example, in a verbose logging mode we could indicate that we're ignoring the schema type due to the presence of an enum clause. However, ultimately this is on you as a schema author to diagnose and learn from.

I highly recommend setting up a robust set of schema linting rules which are run prior to types-generation.

I'll see if this can get some traction in the OpenAPI spec to forbid enum + non-primitive type combinations, but the possible taxonomy of primitive types is frustratingly large, and would force the specification authors to opt between an allow-list and deny-list approach to validating these combinations, which is a prime ingredient in any quadratic-complexity-explosion recipe.

Perhaps this is an impetus to reconsider Stoplight and seek more-stringent tools.