📣 v6.0 RFC and call for contributors

[drwpow]

👯‍♂️ v6.0

openapi-typescript has an upcoming 6.0 version, which started as a breaking change but has now expanded to include the following as well:

• OpenAPI 3.1 support
  • polymorphism ([string, null] definition is converted to unknown #969)
  • discriminator (Map oneOf with discriminator to sum type #953)
• Closer adherence to the spec
• Better JSDoc comment generation
• Library cleanup to make contributions easier
• Improvements to the formatter (now called transform())

🤝 Call for contributors

This library would love to have more contributors and maintainers help keep this project going! In service of this, I’ve recently added:

• Issue templates for better bug filing
• Improved contributor docs to make contributions friendlier
• Codebase cleanup that makes onboarding simpler.

If you’ve been interested in contributing to opensource, or if you’ve found this tool useful at your workplace or personal projects and would love to contribute, please raise a hand ✋! Anyone of any skill level and experience with the project is welcome 🙂

Note that at this time, contributing monetarily isn’t necessary. Perhaps in the future, but for now this library is held back by time constraints and number of maintainers.

❓ v6.0 RFC

Would love some 👍 or 👎 (comments welcome) on the following changes for 6.0 and beyond:

❓ 1. Dropping Swagger 2.x support

Swagger 3.0 has been out for 5 years now and already many (most?) APIs have fully made the leap to 3.x. Anecdotally I haven’t seen an active 2.0 schema in the wild for quite some time. Dropping support for 2.x would shed quite a bit of dead weight in the codebase and allow for faster releases. Of course, users of Swagger 2.x could always use openapi-typescript@5 indefinitely to generate types for their 2.x schemas, but won’t receive any future updates.

❓ 2. Dropping Prettier

Prettier was originally added as a lazy way to clean up the generated output. But with the in-progress code improvements, the output is much better formatted to the point Prettier isn’t needed (to be clear, the output doesn’t and never will match Prettier 100%, but it’s still formatted neatly to the point Prettier isn’t needed). Dropping Prettier would mean much faster generation (initial testing shows a 3× speedup on large schemas) and it would also shed this library’s weight by quite a bit. And users could use their formatting method of choice (#959).

❓ 3. Keeping string manipulation (over AST transformation)

There are 2 types of codegen libraries: those that use string manipulation, and those that use AST transformation. This library uses the former initially out of expediency, but over the years has stuck with this pattern for ease of maintenance and performance. Even though there’s no change here, the idea of switching to TypeScript’s AST has been raised before, and I wanted to raise it again. I won’t explain the pros/cons of each here, because if no one reading is familiar with how ASTs work I think I’ve made my point and ASTs would be harder to maintain 😉. But regardless, thoughts are welcome for those that have them here.

❓ 4. [Insert your idea here]

If you’d like to propose something not mentioned here, either as a breaking change or as a feature request, please speak now! For ideas, you can look back at suggested enhancements that haven’t been implemented yet.

---

🙏 Thanks so much for all the support you’ve given this library. I can’t believe a simple little tool we made at a past company has resulted in millions of downloads and is used in thousands of projects. Thanks for all the PRs, bugfixes, and passionate contributions made by this community!

Here’s to an even better, and faster v6 (and beyond) 😎

[drwpow]

Update: this is largely done in #968. Once that merges, it’ll just take some testing and possibly adding some more tests (many tests were streamlined, and many, many tests were combined wherever possible).

[drwpow]

v6.0.0 shipped! 🎉

The call for contributors is still open. Any bug testing and PRs fixing bugs are welcome!

[denosaurtrain]

Nice work, @drwpow! I've been trying out v6 recently, but I used Deno which added a bunch more confusion for me, so I don't have much helpful feedback for you. Just want to say thanks for the good work!

[yacinehmito]

Raising a hand 🤚
(that doesn't exist as a reaction, sorry)

I plan to use openapi-typescript extensively at our company. I have a keen interest in making the library portable to other runtimes (browser, Deno, Cloudflare Workers), without compatibility layers.

[npbenjohnson]

👍 Use AST - With a utility library like ts-morph, and an AST tool like https://ts-ast-viewer.com/, I think using AST would actually lower the barrier to entry for contributing to this project. It is a lot more effort to understand the branching generation logic in this library, and find a reasonable place to extend it if the injection point required is not already a point being filled in. If it used AST, making a modification could just be selecting the correct node(s) on the existing output and making the modification. It would also allow for more easily composing structures that may be created in more than 1 pass, like for updating jsdoc comments when the related structure changes.

[rxliuli]

AST is actually not as complicated as imagined, you can look at ast-types/recast, their abstraction of AST is very elegant, much simpler than the AST of typescript compiler, it is just a constantly nested JSON object, you can use JS recursion Traverse or use tools to query specified nodes.
astexplorer allows viewing the ast structure, again, it's much simpler
https://astexplorer.net/

ast-types example

const ast = b.exportNamedDeclaration(
  b.tsInterfaceDeclaration(
    b.identifier('User'),
    b.tsInterfaceBody([
      b.tsPropertySignature(
        b.identifier('name'),
        b.tsTypeAnnotation(b.tsStringKeyword()),
      ),
      b.tsPropertySignature(
        b.identifier('age'),
        b.tsTypeAnnotation(b.tsNumberKeyword()),
      ),
    ]),
  ),
)

ts api example

factory.createInterfaceDeclaration(
  undefined,
  [factory.createModifier(ts.SyntaxKind.ExportKeyword)],
  factory.createIdentifier('User'),
  undefined,
  undefined,
  [
    factory.createPropertySignature(
      undefined,
      factory.createIdentifier('name'),
      undefined,
      factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
    ),
    factory.createPropertySignature(
      undefined,
      factory.createIdentifier('age'),
      undefined,
      factory.createKeywordTypeNode(ts.SyntaxKind.NumberKeyword),
    ),
  ],
)

However, I even wrote a generator that uses ast-types to generate code, e.g.

input

export interface User {
  name: string
  age: number
}

output

b.exportNamedDeclaration(
  b.tsInterfaceDeclaration(
    b.identifier('User'),
    b.tsInterfaceBody([
      b.tsPropertySignature(b.identifier('name'), b.tsTypeAnnotation(b.tsStringKeyword())),
      b.tsPropertySignature(b.identifier('age'), b.tsTypeAnnotation(b.tsNumberKeyword())),
    ])
  )
)

ref: https://gist.github.com/rxliuli/d5286a1ea6d028c25e7b26c338ceac58

[benevbright]

Is it currently possible to get paths as an object for runtime?