|
|
|
|
|
|
by whizzter
1086 days ago
|
|
|
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). |
|
|
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.