V7 Preview

[drwpow]

V7 Preview 🎉

This is one of the most exciting releases in this project’s history—this uses the Redocly CLI (#1344) to validate schemas and report errors ✨.

You can test it out today at:

npm i openapi-typescript@next

🙏 If you’re able to test this out and report any errors it’d be much appreciated.

📖 v7 Documentation

Overview

• 🚀 Drastically-improved performance for multi-file schemas. Performance is a teeny bit slower for single-file schemas (an extra half-second) but not a drastic drop
• ✨ The Redocly CLI now validates & bundles schemas, which means better UX for users and reduced project maintenance
  • The codebase itself got a dramatic reduction in logic
• 🌲 Leveraging the TypeScript AST means greater accuracy without compromising speed
  • Also, using the official TypeScript lib means no feature drift, no chance of project abandonment, and bleeding-edge updates
• ✨ This also adds the hotly-requested feature top-level enums ([Feature request] Generate Enums AND Union types #941).

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.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 68a1a5c

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

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Pages

Latest commit:	68a1a5c
Status:	✅  Deploy successful!
Preview URL:	https://e2a53ab1.openapi-ts.pages.dev
Branch Preview URL:	https://v7.openapi-ts.pages.dev

View logs

[wolfy1339]

This looks awesome!

There seems to be an issue compiling OpenAPI 3.1 specs.

Error: Unsupported schema format, expected `openapi: 3.x`
    at validateAndBundle (node_modules/openapi-typescript/dist/lib/redoc.js:88:15)
    at async openapiTS (node_modules/openapi-typescript/dist/index.js:31:20)
    at async run (openapi-webhooks/scripts/generate-types.js:90:9)

I looked into this with a debugger, and it seems that document.parsed is not an object but a string, which means that document.parsed.{swagger,openapi} will be undefined because those properties do not exist on the string object.
The value that I see for document.parsed is the path to the spec file.

Going further up the call chain, in the parseSchema function, the file doesn't seem to be loaded anywhere. It simply is the path to the spec that is passed around

EDIT: This seems to happen only when passing a string path to openapi-typescript, passing a URL of the path

You can find the spec I am trying to compile here: https://github.com/wolfy1339/openapi-webhooks/blob/main/packages/openapi-webhooks/generated/api.github.com.json
(It's GitHub's OpenAPI 3.1 specs with only webhooks, all routes deleted)

[drwpow]

There seems to be an issue compiling OpenAPI 3.1 specs.

EDIT: This seems to happen only when passing a string path to openapi-typescript, passing a URL of the path

This might be behaving as expected, if you’re using the Node.js API. Since this is a major version, there are a couple breaking changes, especially with how schemas are loaded. Specifically, passing a partial string path is no longer supported; if you’re referring to a file you should pass a URL() instead. Or pass the file contents as a string. Please check out the updated docs here and let me know if this fixes your issue: https://v7.openapi-ts.pages.dev/node/

[drwpow]

An overdue addition to v7 is enforcing that the generated TypeScript doesn’t contain any type errors. Before, this checked happened manually. But going forward it will be enforced automatically by CI.

However, the DigitalOcean schema is a bit of a love–hate relationship. On the one hand, it does really stress-test many of the features that make this library robust and flexible (like being the biggest example I can find of abusing remote schemas). But on the other, the schema itself has errors 🙃.

Unfortunately, this means we can’t use DigitalOcean’s schema to check errors until they themselves resolve the problems with their schema. But I still like having it around for snapshot testing to just make sure this library can generate something there without blowing up. So until the errors are fixed, it’s excluded from the type error check

[drwpow]

The upcoming v7 will require more testing before release (release date TBD), but I’m going to merge this into main, and fork the current main into 6.x for bugfixes and security updates.