support conditional ts enums

[danitt]

Changes

Adds support (via optional flag) for generating TS Enums only where there is relevant metadata.

TS Enums can provide useful mappings in specific circumstances:

enum ThingId {
  Variant1: 'f49c3b85-5cfe-473a-8ce7-f876788d211a',
  Variant2: '50f5ddfc-217c-4507-a875-165a5bbf5a41',
  Variant3: '41b85275-8018-4398-9c4f-379dbf198fc8',
}

but is also entirely redundant in many others:

enum Status {
  ok: 'ok',
  pending: 'pending',
  error: 'error',
}

This PR provides an optional --conditional-enums flag to only create TS Enums where relevant mapping metadata has been explicitly added:

components:
  schemas:
    Foo:
      type: string
      enum: [pending, active, done]
    Bar:
      type: string
      enum: [pending, active, done]
      x-enum-varnames: [Pending, Active, Done]
      x-enum-descriptions: [
        "The task is pending",
        "The task is active",
        "The task is done",
      ]

Converts to

export type Foo = 'pending' | 'active' | 'done';
export enum Bar {
  // The task is pending
  Pending: 'pending',
  // The task is active
  Active: 'active',
  // The task is done
  Done: 'done',
}

The particular use case I am targeting is for established code bases that rely 95% on simple type unions, but may occasionally wish to store enum mappings in OAPI where appropriate.

This feature would assist in cases such as #941 and #2366.

How to Review

1. Prepare an OAPI schema with two kinds of enums, one with metadata and one without (see above Status / StatusEnum example).

2. Test generating typings with the enum flag enabled, and then toggle the conditionalEnums to compare the differences in result.

Checklist

• Unit tests updated
• docs/ updated (if necessary)
• pnpm run update:examples run (only applicable for openapi-typescript)

[changeset-bot]

🦋 Changeset detected

Latest commit: ad43b6a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
openapi-typescript	Minor
swr-openapi	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

❌ Deploy Preview for openapi-ts failed.

Name	Link
🔨 Latest commit	ad43b6a
🔍 Latest deploy log	https://app.netlify.com/projects/openapi-ts/deploys/68be7112db63ff0008dca7a9

[danitt]

hi @htunnicliff it seems the build failures are due to an issue fetching a particular github contributor:

• https://github.com/openapi-ts/openapi-typescript/blob/main/docs/scripts/update-contributors.js#L231
• https://app.netlify.com/projects/openapi-ts/deploys/68be7112db63ff0008dca7a9

did you want me to amend the logic in update-contributors.js to fail gracefully if a user can't be resolved? I'm just cautious of over-extending the scope on this PR

[danitt]

hi @drwpow I don't suppose you could take a look please?