How OpenAPI Undermines a Good Developer Experience

D.S. — Fri, 03 Oct 2025 09:36:41 +0000

In the JavaScript/TypeScript ecosystem, tools like tRPC and oRPC are gaining traction. This isn’t by chance, it signals a growing need in the JS world: moving beyond the Developer Experience imposed by OpenAPI’s schema-first approach. But why?

All OpenAPI Code Generators Are Broken

With the help of Gen-AI, I'm building a tool to generate TypeScript code from OpenAPI specs. Fighting against the standard, I uncovered a systemic issue:

All existing code generators are unreliable, and it couldn’t be otherwise.

OpenAPI specs are unnecessarily complex, creating a chaotic mess for anyone trying to automate code generation. Here’s why.

Error Handling Chaos

Error handling in OpenAPI requires a sisyphean effort. You must manually map different layers: network errors (failed fetch), server errors (5xx), client errors (4xx), and payload serialization/deserialization issues.

Each status code - (ie. 404 returning nothing, 429 providing retry parameters, 400 delivering unpredictable serialization errors, ...) may (or not) come with a payload in wildly different formats with disconnected meanings.

Therefore, a client generator cannot merely "implement retries": users must handle all this logic themselves by interpreting the returned data.

Serialization Nightmare

Take parameter serialization (ie. style and explode). You can send textual data to an endpoint in seven different ways with the same outcome. This redundancy is there for legacy reasons, pointless and breeds ambiguity everywhere.

JSON Schema Quirks

JSON Schema is a minefield of edge cases. For example, you can have an allOf intersection with and empty object that specifies a list of required fields without any schema attached.

SomeSchema:
  allOf:
    - $ref: "#/components/schemas/SomeOtherSchema"        
    - $ref: "#/components/schemas/SomeOtherSchemaAgain"
    - type: object
      required: [foo]

The generator implementation must traverse all fields of all objects in the intersection, only to mark as required - if any - those referenced by this empty object. Guess what? No know tool handles this.

Wildcard Complexity

Generators must handle vague cases like range status codes (e.g., 4XX, 5XX, ...) alongside the "default" case, adding yet another layer of complexity that’s nearly impossible to manage keeping a good DX.

A Challenge

With so many intersections and details, no tool can handle every scenario. TypeScript developers today are working with tools that are merely "good enough," if that’s even sufficient.

What’s the point of a spec if its core purpose - automatic code generation - is inherently flawed?

All existing TypeScript generators are approximate at best. You can verify this yourself against a valid OpenAPI spec.

Try find a generator that correctly handles:

Different schemas for multiple 2xx responses
Different schemas per content type
Default responses
Range status codes
Intersections with empty objects
Self references

Time to Rethink the Paradigm

Recently, I came across the Cap'n Web protocol from Cloudflare, and it clearly demonstrates a unified approach that delivers a DX unthinkable with OpenAPI.

OpenAPI solves problems that shouldn’t exist in the first place. The schema-first approach is doomed to deliver a subpar DX. It's so poor that Microsoft decided to implement its own alternative DSL just to produce OpenAPI specs. Entire commercial companies have their core product built around being a decent OpenAPI code generator (!).

For a new project - especially internal services - I would rather lean towards DX-friendly alternatives like modern RPC protocols or a code-first approach where the API specification is generated directly from the source code.

Are you using OpenAPI for internal APIs, or have you switched to something more streamlined?

OpenAPI to TypeScript: a More Reliable and Type-Safe Approach

D.S. — Sun, 14 Sep 2025 22:42:32 +0000

If you’re building REST API clients (or servers) with TypeScript, you expect type safety to save the day. But most existing OpenAPI-to-Typescript generators give a false sense of security, hiding pitfalls that can bite in production. After benchmarking 20+ tools, here’s what I found, and how I choose to fix it.

Poor error handling

Calling

const ret = await api.post({ ... })

should be safe, but the method signature often ignores network issues like DNS failures or timeouts. You’re forced to wrap it in a try/catch, but without clear documentation on what errors to expect, you’re left guessing. Even when documented, this approach is fragile and prevents efficient error handling as validation errors (versus OpenAPI specs) end up in the same bag as network errors.

Limited handling of HTTP statuses

Most generators emit types only for 2xx responses, ignoring 4xx/5xx errors with specific payloads. If the API returns a 400 or 500 with some ProblemJson, generated TypeScript types (and/or runtime schemas) won’t reflect it, leaving you vulnerable to runtime surprises.

Multiple success responses, different payloads

Some APIs return different payloads for 200 vs. 201 status codes. Many generated clients only handle the first successful status code. Other clients either treat non-200 responses as unknown errors, or merge them into some vague Typescript union, forcing further runtime checks to discriminate. What’s the point of using the generated code then?

Mishandled default responses

The smartest generators create discriminated unions for all response types (200, 201, 400, 500, etc.), but default responses (covering unspecified cases in OpenAPI) are treated as generic errors and/or lack payload typing and validation, leading to inaccurate types.

Content-type being ignored

APIs returning multiple content types require discrimination by both status code and content-type. Afaik, no existing Typescript generator supports this. Ideally, you should be able to write:

if (r.status === 200) {
 if (r.contentType === "application/json") {
    // Typescript should know that r.data is SomeJsonModel
  } else if ( r.contentType === "application/xml") {
    // Typescript should know that r.data is SomeXmlModel
  }
}

OpenAPI Schema mismatch

OpenAPI schemas are more expressive than TypeScript types. For example, a schema defining an email string or regex pattern often becomes a plain string in TypeScript. Even tools with runtime validation struggle to support advanced OpenAPI features like string patterns or oneOf vs anyOf, leading to inaccurate types and runtime bugs.

Conclusion

After evaluating the landscape, I faced a dilemma: convince maintainers of top tools to adopt breaking changes for their thousands of users or build a new solution from scratch. I chose the latter and built an open-source TypeScript client generator that prioritizes safe, accurate types and excellent Developer Experience:

https://gunzip.github.io/apical-ts/

What's your biggest pain point with generated OpenAPI clients / servers?

I’d love to hear your thoughts to shape this project, drop a comment, or check out the prototype!

Forem: D.S.