Comment by BuckyBeaver | Hacker News Reader

Comment by BuckyBeaver | Hacker News Reader

Parent Full thread

What are you trying to do in regard to your API? I just developed an extensive API definition using OpenAPI, which (as of version 3.1) is compliant with JSON Schema. I used Stoplight Studio on Mac OS, although it still doesn't fully support OAS 3.1 two years after it became the current OpenAPI standard. The support from tools and generators is terrible; there's still no apparent toolchain that supports version 3.1 from definition through code generation.

Ass-dragging on 3.1 support aside, the code-generation tools out there are, in my experience, trash anyway. It's a massive hodgepodge of Java-based tools with incomplete and redundant documentation repositories all over the place, and widely varying output quality... when the tools work at all. I appreciate people giving their time to open source, but on the other hand I wasted so much time trying to make the broken tools work that I could have written my own code generator from scratch (which is what I ended up deciding to do after weeks of dicking around with OpenAPI Generator).

Anyway, I was just wondering how you're using JSON Schema for API work (since you didn't mention OpenAPI).

I spent the last year and half working on a project where we planned to use OpenApi/AsyncApi to generate typed api clients and validate api requests between all our services and applications (written in typescript & C#).

Going into it, I thought we'd be on a well traveled path, but that was far from the case...

Typescript has some decent code generation packages (although fragmented) and request validation can be hacked via AJV... But tooling around C# was halfbaked at best.

In the end, I didn't really feel like OpenApi provided the API "contract" I had originally hoped for.

If I could start over, I would probably use something like gRPC for internal service communication (would maybe still use OpenAPI for any public API)

This is exactly what I expected: a well-traveled path. I assumed I was doing something wrong or just not "getting it," and spent weeks digging through the scattered doc and poring over Java code and templates... and the generated code, which wouldn't even compile. In our case, we needed C++ for client and server... a hugely under-served scenario.

Using OpenAPI and Stoplight was very useful for thinking the API through and how the whole thing could work, but the code-generation aspect was a total bust. And talking to some new colleagues later who had some knowledge of it, I found that I wasn't alone in my opinion that the tooling is trash.

Even worse, the prevailing opinion on the ecosystem is so poor that it might even be a professional liability to propose (or admit to) using it. The implication was that it (or at least the code-generation facilities for it) is by and for people who don't know what they're doing. Oof.

It's kind of insane how stoplight and swagger/smartbear still don't support OpenAPI 3.1

Half tempted to just start building out OA3.1 stuff to replace those services

This is what I was going to do too. I was just going to write a code generator in Python.

And I don't even know Python. I figured it'd be easier to learn it and use it for text processing than wasting any more time trying to make the sprawling Java "tools" work.

I am planning to autogenerate a set of Java libs from OpenAPI 3.1 definitions in an upcoming project, and so far have assumed it would Just Work. Am I going to have a bad time?

It's hard to say. It may be that the Java ecosystem for it is in good shape. The generator tools are almost all Java, so you might have the best-case scenario.

The OpenAPI Generator uses Mustache templates and a plug-in-style design to handle all the different languages and outputs targeting different packages. I was never able to find a succinct document explaining exactly how the processing steps worked or even a catalog of data elements that the generator extracted from your OpenAPI spec document (YAML or JSON). So while there's a lot of talk about creating a custom template, or, if that's not enough, a custom generator... the documentation to do so is very incomplete. The only example I found all discussed making a generator for documentation and not code. Again, not to sound unappreciative, but... that's lame.

Reply on news.ycombinator.com