[DidYaWipe]

I don't work in an office or on a team. Top bad-day causes I find in self-employed dev situations:

1. Bad or no documentation on tools or technology being used

2. Defects in tools being used

These are so bad now that I just don't even want to be in the field anymore much of the time. For either of them, you're often reduced to spraying all the usual forums with a question (and it takes ages to prepare a reproducible case that you can actually share, if that's even possible) and then waiting and hoping. Oh, and in the meantime doing the same searches over and over to see if some previously hidden nugget will turn up and reveal a solution.

[calderwoodra]

Can you share an example? I rarely have this problem, likely because I bias towards building it myself and only bring in outside tools when there's significant time savings

[DidYaWipe]

Sure. Right now I'm trying to port a just-started project from a pure-Deno back-end to Supabase. I'm building a back end for a mobile application.

But if you're not building another Web SPA, it's as if you don't exist for a lot of these frameworks. And doing simple stuff like deploying your own certificates is undocumented. Also they have a users table whose columns are undocumented and behave in unexpected ways. For example, they have columns to record whether and when a user has been validated (confirmed via E-mail), and for some reason these are set upon new-user creation... when they certainly have not been validated. Why? Who knows.

Another example: I was tasked with defining a REST-style API for a line of products. After learning about OpenAPI, I thought great, I'll design it in an OpenAPI tool and that'll be the source of truth for both front- and back-end code generation.

Fat chance. The OpenAPI ecosystem turned out to be a dysfunctional shitshow. First, the current version (as of years ago) is 3.1. But to this day, almost no tools support it. Version 3.0 was profoundly flawed in several ways. And even tolerating that, the 3.0 code-gen tools just straight-up don't work. Plus, the design tool I was using (Stoplight Studio) has been pulled off the market, and nothing has emerged to replace it. The whole thing was a huge time-suck. I talked to some developers about it after the fact and they said yeah, the whole thing is so bad that even mentioning you were using it is a professional liability.

Defect example: iOS 18 broke trusted certificates (still not fixed in 18.1), so currently you can't develop a network-dependent app on iOS on your own system. When I tried to work around that by targeting my Mac and using HTTP to localhost, another Apple bug caused the app to crash on launch before even getting to my code. So... dead halt to development for a week, despite my opening a paid support incident with Apple. They did finally get back to me and gave me a workaround to the crash-on-launch bug (no charge because confirmed bug), but damn.

More days lost. I had stretches like this before, and then the logjam breaks and I really start making headway. But this shit has been a slog for months.

[florianmartens]

Try api-fiddle.com as a replacement for stoplight.io :)

[DidYaWipe]

Thanks for that. Took a look at it, and... it doesn't handle 3.1 documents correctly. One of the major defects in the OpenAPI document spec pre-3.1 is that you can't put descriptions on any usage of a model in your API. I mean... WTF?

So if you had a data structure called User, and you used it to represent users in different roles in your API somehow, you can't annotate the instances of User in your document to say what kind of user you're talking about. You can annotate the elements inside the User model (like strings, numbers, or whatever) but not usages of the model itself. Before version 3.1, this blunder rendered OpenAPI half-useless for one of its core purposes: documenting your API.

API-Fiddle acts as though that's still true. There is no Description button anywhere in your schema alongside any use of a model.

[DidYaWipe]

Update on that: I contacted the developer and he fixed that problem in a matter of minutes. Pretty cool!