[lelanthran]

> Why no type checking? Generate an Open API client for target languages.

I dunno. Why aren't more people using openapi?

What I see in practice is that almost everyone is using JSON as the transport mechanism and not generating that JSON serialisation code from open API specs.

The type-checking in CORBA was not opt-in, it was mandatory.

Type-checking in browser fetch() calls are optional. To opt-in you have to go outside of the standard.

[whizzter]

We use OpenAPI/Swagger specs whenever possible for new projects and integrations (some usages or integrations are older).

Generating a OpenAPI/Swagger spec in .NET is as easy as telling a lib like NSwag to generate and publish documents from your API's (and you can filter out to only show public API's in the docs). Probably as easy in Java,go,etc.

Consuming services can usually be done almost as easily by downloading the spec and pointing a code-generator to it.

HOWEVER the mandatory vs opt-in part is why we are stuck with JSON based api's, consuming/providing the typings becomes extra work when interfacing/playing with an API from any dynamic language such as JS, Python, Ruby, etc whilst you really only pay a relatively minor performance penalty from typed languages that people won't care about in dev up until it hits in production (Assuming you have an modern JSON serializer library built for speed).

Anything resembling "bloat"/complexity (sadly types is in this category from the perspective of many anti-TS JS developers, esp as API-typings still won't come from the host language but having to be provided separately) will be offputting and lead to any such spec being ignored by a substantial chunk of developers.

[crabbone]

OpenAPI isn't worth using. It's so pathetically bad, that it's not worth the effort.

Those who use it (eg. Kubernetes) do it for show, to put another badge on their Github repo page, to sound more sophisticated and "in the know" than they actually are.

[littlecranky67]

From my experience, code generators arent stable and reliable enough. Whenever I was in a project where either side (Backend/Frontend) generated code from OpenAPI/Swagger spec, they broke at some point - weeks after introducing, by using some new feature/syntax in the specfile.

Given that they produce human unmanageable/readable code, ejecting was a terrible solution.

[whizzter]

Out of curiosity, what front/backend languages was involved in this? OpenAPI/Swagger has various functionality for supporting polymoprhism but this is usually where problems crop up in my experience due to the mismatch between how languages support it.

In our setup, the server is usually C# and we restrict the API's to primitives, records/objects (without inheritance) and lists of the previous. None of this has ambigious mappings when it then comes to the frontend (Typescript) side, the Typescript side then mostly benefits from client-side typings for developers but actually validating isn't always done if we only have SPA consumers (Incompatible upgrade -> new cloned endpoint for the duration of the upgrade period).

[littlecranky67]

It was mostly TypeScript and C#. Stuff gets worse when you use a generated swagger specfile from code, and then try to feed this into any other generator.

But when hand-writing openapi specs, there are a lot of features that are not understood by generator or lead to subtle bugs. Stuff like intersections, mixins (oneOf, allOf, anyOf, not), and union types (with named discriminators) are a thing in OpenAPI but kind of are hard to map to C# or Java for that sake. And the way you can map it, is strongly opinionated and might be different between generators (or their templates). But also other stuff, like non-supported `$ref` statements where giving us a headache.

If you start out with generators and are willing to compromise on API cleanliness (i.e. workaround by changing the OpenAPI spec when a bug in the generator arises) you might be fine.

But in cross-department or even cross-company teams, with hand optimized API definitions (specfiles), I wouldn't take the risk. I cannot emphasize risk here enough. Yes, you might be fine for a while. But you receive a new version of the specfile, and suddenly the output generated code breaks, won't even compile. This is a huge problem. You can fight whoever gave you the specfile to revert the changes, but if it passes the OpenAPI test suite, you will have a hard time arguing. So you suddenly have to eject the generated code and hope you can make changes - usually its unmaintainable, unreadable generated code. Alternatively, this is the moment when you rip out the generator and re-implement everything by hand.

Just beware, when chosing a generator, you make a bet that it is mature and bug-free enough to handle all cases that will come during project lifetime - and you bet a significant amount risk to that maturity. And if you know of any rock-solid, battle-tested generator for C# and/or TypeScript, please share. I only see either outdated ones with 100+ github issues per year, or relatively new players that lack a track record. And neither is company/money backed, so you rely on someones open-source work.

[winrid]

It helps a lot to keep your interfaces simple and flat. Probably too late for your project but I always advocate for this - then integrating with other systems and languages is much easier.

[littlecranky67]

I fully agree with you. If you keep your API simple, reasons for code generators disappear and are quickly drafted by hand.