Add a flag to skip Schema prefix when rendering root types

[sultaniman]

Changes

This PR adds another cli flag --root-types-no-prefix which complements --root-types.
If set it will render root types without Schema prefix.

Checklist

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: fb59371

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[drwpow]

In favor of this in general! I think we need some tests here just to ensure it works as expected, but that test can be minimal since it’s an opt-in flag.

Also agree with the “off/on” approach here, since the prefixes MAY be Schema but also may be Response or Request, etc. I don’t think it would make sense to have a flag to manually set that prefix, since that prefix isn’t hardcoded to begin with.

But with that in mind, a test that **tests what happens when you have a naming conflict between #/components/schemas and #/components/responses would be great (not required, but it would really help validate that all bases are being covered)

[sultaniman]

Hey @drwpow thanks for review, I will add tests and update the PR with requested changes some time next week.

[sultaniman]

@drwpow I will add another test which tests when there is a parameter with the same name. I added a test case for the new flag.

[sultaniman]

@drwpow can you please take a look again?

[drwpow]

Sorry for the delay. This looks FANTASTIC. Thank you!

[sultaniman]

That's awesome, thanks @drwpow!

[fluctus]

@sultaniman @drwpow First, great job on adding the new --root-types-no-prefix flag! It’s a really useful addition.

However, I've noticed that when the --root-types-no-prefix flag is used alongside the --enum flag, it generates a root type with the same name as the enum, leading to naming conflicts.

Given that enums already serve as types in TypeScript, it seems unnecessary to generate a separate root type in these cases. Skipping the root type when both flags are used would help avoid conflicts and streamline the output.

It would be great if this could be addressed, whether by skipping the root type or considering other potential solutions to prevent such conflicts. Looking forward to seeing how this can be improved!

[sultaniman]

Hey @fluctus @drwpow I think I can adjust with additional check if --enum flag is passed then maybe skipping prefix trimming, but probably we first need to discuss the desired behavior.

[fluctus]

👋 Good point @sultaniman. Regarding the desired behavior, I think it would be a bit odd if this feature doesn't work when the --enum flag is used. A better solution might be to make both flags work together without conflicts.

One option could be to skip generating the root type only for enums when both the --root-types-no-prefix and --enum flags are used. This would avoid naming conflicts while keeping the intended behavior intact. If there's another way to handle both flags together without issues, that would work too.

[drwpow]

Yeah with some of these flags, they’re not always perfectly compatible with one another. We could either throw an error that these flags don’t work together. Or do what @fluctus suggested by modifying the behavior of --root-types-no-prefix. As long as we DON’T modify the behavior of the --enum flag in any way I think that’s a fine solution.

[sultaniman]

alright then as @fluctus suggested it would mean if --enum is passed then we skip --root-types only for enums?

[fluctus]

@sultaniman if @drwpow agrees with this solution, would you be handling the fix?

[sultaniman]

Hey @fluctus sorry for being slow, I was sick, will try to carve out some time this week for it.

[fluctus]

@sultaniman No worries, hope you're feeling better! Thanks for taking the time to look into this.

[sultaniman]

@fluctus can you please provide some minimal OpenAPI spec example with enum definitions you have?

[fluctus]

@sultaniman Sure, this is a sample spec that generates types with the same name for enums:

openapi: 3.0.3
info:
  title: My API
  version: 1.0.0
components:
  schemas:
    NonEnumSchema:
      type: string
    EnumSchema:
      type: string
      enum:
        - VALUE1
        - VALUE2

Without --root-types-no-prefix:

export type paths = Record<string, never>;
export type webhooks = Record<string, never>;
export interface components {
    schemas: {
        NonEnumSchema: string;
        /** @enum {string} */
        EnumSchema: EnumSchema;
    };
    responses: never;
    parameters: never;
    requestBodies: never;
    headers: never;
    pathItems: never;
}
export type SchemaNonEnumSchema = components['schemas']['NonEnumSchema'];
export type SchemaEnumSchema = components['schemas']['EnumSchema'];
export type $defs = Record<string, never>;
export enum EnumSchema {
    VALUE1 = "VALUE1",
    VALUE2 = "VALUE2"
}
export type operations = Record<string, never>;

With --root-types-no-prefix:

export type paths = Record<string, never>;
export type webhooks = Record<string, never>;
export interface components {
    schemas: {
        NonEnumSchema: string;
        /** @enum {string} */
        EnumSchema: EnumSchema;
    };
    responses: never;
    parameters: never;
    requestBodies: never;
    headers: never;
    pathItems: never;
}
export type NonEnumSchema = components['schemas']['NonEnumSchema'];
export type EnumSchema = components['schemas']['EnumSchema'];
export type $defs = Record<string, never>;
export enum EnumSchema {
    VALUE1 = "VALUE1",
    VALUE2 = "VALUE2"
}
export type operations = Record<string, never>;

Which results in these TS errors:
TS2502: EnumSchema is referenced directly or indirectly in its own type annotation.
TS2456: Type alias EnumSchema circularly references itself.
TS2567: Enum declarations can only merge with namespace or other enum declarations.

[sultaniman]

@fluctus thank you very much for providing an example I will use it in the tests.

[theo-staizen]

Hi @sultaniman @fluctus I have also run into exactly those 3 errors, because I was running both --root-types-no-prefix and --enums. Is there no way to fix this and keep both flags?

[fluctus]

@theo-staizen yes, @sultaniman is working on a fix that will work with both flags.

[sultaniman]

Hey guys, sorry for delays I wanted to work on this last week but was unable to do so. I will do it in the coming weekend and the following week.

[theo-staizen]

hi @sultaniman, sorry to bother you, but have you had a chance to work on this at all? is there anything we can do to help?

[sultaniman]

Good evening @drwpow @theo-staizen @fluctus sorry for being so slow had many personal things going on recently. I linked the PR which disables --root-types-no-schema-prefix if used with --enum flag.