v7 Preview 🎉

[drwpow]

v7 Preview

openapi-typescript@7 is now in preview! 🎉 The major additions to this library are:

• ✨ Built-in validation using the Redoc CLI — no more needing an external tool
• ✨ Respecting redocly.yaml for API config (define your schemas there in one place, and use openapi-typescript to generate TypeScript without having to manage a separate config)
• ✨ Addition of the --enum flag for generating true TypeScript enums instead of unions (default behavior still unions)
• 📘 A mini-rewrite to use the TypeScript AST instead of string mashing

Full Changelog

Features

• ✨ Feature: automatically validate schemas with Redocly CLI (docs). No more need for external tools to report errors! 🎉

  • By default, it will only throw on actual schema errors (uses Redocly’s default settings)
  • For stricter linting or custom rules, you can create a redocly.yaml config

• ✨ Feature: bundle schemas with Redocly CLI

  • Any options passed into your redocly.yaml config are respected

• ✨ Feature: add enum option to export top-level enums from schemas ([Feature request] Generate Enums AND Union types #941)

• ✨ Feature: add formatOptions to allow formatting TS output

• ✨ Feature: header responses add [key: string]: unknown index type to allow for additional untyped headers

• ✨ Feature: allow configuration of schemas via apis key in redocly.config.yaml. See docs for more info.

Breaking Changes

• ⚠️ Breaking: The Node.js API now returns the TypeScript AST for the main method as well as transform() and postTransform(). To migrate, you’ll have to use the typescript compiler API:

  + import ts from "typescript";
  
  + const DATE = ts.factory.createIdentifier("Date");
  + const NULL = ts.factory.createLiteralTypeNode(ts.factory.createNull());
  
    const ast = await openapiTS(mySchema, {
      transform(schemaObject, metadata) {
      if (schemaObject.format === "date-time") {
  -       return schemaObject.nullable ? "Date | null" : "Date";
  +       return schemaObject.nullable
  +         ? ts.factory.createUnionTypeNode([DATE, NULL])
  +         : DATE;
        }
      },
    };

  Though it’s more verbose, it’s also more powerful, as now you have access to additional properties of the generated code you didn’t before (such as injecting comments).

  For example syntax, search this codebae to see how the TypeScript AST is used.

  Also see AST Explorer’s typescript parser to inspect how TypeScript is interpreted as an AST.

• ⚠️ Breaking: Changing of several CLI flags and Node.js API options

  • The --auth, --httpHeaders, --httpMethod, and fetch (Node.js-only) options were all removed from the CLI and Node.js API
    • To migrate, you’ll need to create a redocly.yaml config that specifies your auth options in the http setting
  • You can also set your fetch client in redocly.yaml as well.
  • --immutable-types has been renamed to --immutable
  • --support-array-length has been renamed to --array-length

• ⚠️ Breaking: Most optional objects are now always present in types, just typed as :never. This includes keys of the Components Object as well as HTTP methods.

• ⚠️ Breaking: No more external export in schemas anymore. Everything gets flattened into the components object instead (if referencing a schema object from a remote partial, note it may have had a minor name change to avoid conflict).

• ⚠️ Breaking defaultNonNullable option now defaults to true. You’ll now need to manually set false to return to old behavior.

• ⚠️ Breaking: Remove globbing schemas in favor of redocly.yaml config. Specify multiple schemas with outputs in there instead. See Multiple schemas for more info.

And dozens of small performance improvements and quality fixes.

Give it a try today with the @next flag:

npm i openapi-typescript@next

Testers wanted 🙏

Will pin this issue for a while while people kick the tires and report bugs while a release candidate is developed. For many people, it should be a drop-in replacement; for others, it will only require a few minor changes.

If people could report any errors/issues they face while trying this, that’d be much appreciated. Any issues posted here or as separate issues will help patch holes in the docs site.

[luchsamapparat]

Great to hear that openapi-typescript will support external refs! Thanks a lot for that :)

I did quick test with our project and ran into a typing issue.

When extending a model using allOf...

    PurchasableProduct:
      type: object
      properties:
        price:
          $ref: '#/components/schemas/Price'
      required:
        - price
      allOf:
        - $ref: '#/components/schemas/Product'

... the generated code does not compile:

Our backend colleagues use the same OpenAPI file using the openapi-generator kotlin-spring plugin, so it seems to a be valid spec.

Here's an example repo to reproduce the issue:

https://github.com/luchsamapparat/openapi-typescript-7-bug

[drwpow]

@luchsamapparat the generated code seems to be working correctly; the error seems to be coming from the fact your schema specifies price as a required property but no such property exists. Does removing that fix the error?

[luchsamapparat]

If you have another look at my example, the price property is not only defined as required, but also as a property directly below the properties: line.

You can copy and paste the full example OpenAPI YAML from my repo into the Swagger Editor which parses it correctly:

[ElForastero]

Would be nice to support x-enum-varnames property.

UPD:
Well, I think I did it. Check the PR #1374

[luchsamapparat]

Thanks to @joostme who pointed out that there's a workaround for my problem:

luchsamapparat/openapi-typescript-7-bug@638870c

[stefanprobst]

running with --immutable flag seems to generate invalid ts: export readonly interface paths {}

see:

npx openapi-typescript@next https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.yaml --immutable | head

error:

'readonly' modifier can only appear on a property declaration or index signature.ts(1024)

[drwpow]

@stefanprobst good catch 🙏! Will add some immutable tests to make sure the types are valid.

Sidenote: I did learn through the v7 rewrite that TypeScript’s AST does let you generate invalid TS without stopping you. Which is fun 🙃

[maslennikov]

Upgraded to v7 without issues. Generated file looks neat and tidy - especially when using external file refs. Thank you for this awesome job!

[maslennikov]

@drwpow may it be the case that there were some changes in handling of the | undefined portion of additionalProperties typings? I think, I am noticing now something of it.

Related issues: #1018, #1267

Input:

    CityLinks:
      type: object
      required: [socials]
      properties:
        socials:
          type: object
          additionalProperties:
            type: string

Output

         CityLinks: {
            socials: {
                // There was no `| undefined` in later v6 versions
                [key: string]: string | undefined;
            };
        };

[tonyxiao]

Why is it that we have a ton of never now in v7 whereas they did not exist in v6? it makes the generated types a fair bit more verbose to read.