Is it time to replace Open API Spec with something that’s tailored for code generation and schema first design?

[-]

gredr@reddit

This is... pretty content-free. This guy's frustrated with OpenAPI. He's gonna... make his own.

[-]

heyheymonkey@reddit

Also starting from yaml is unnecessary. So he picked the hardest path through Open API land and is frustrated it’s hard.

[-]

I like designing my APIs schema first because I saw a lot of backend developers ignoring how the APIs are going to be consumed by the frontend, and the spec is a good place where the entire team can form consensus on how the APIs should behave.

[-]

heyheymonkey@reddit

You can still do that by creating API stubs in your language of choice and then generating the schema from that. I’d argue that should be faster than hand-editing anything more than a tiny schema.

As another commenter said, there may be valid reasons to edit the schema yourself if you’re very picky. For getting initial consensus with stakeholders around shapes, it’s totally unnecessary.

[-]

whkelvin@reddit (OP)

I actually like this approach, the only downside is when I switch backend language, I'll have to learn new toolings.

[-]

gredr@reddit

OpenAPI may or may not be good, I dunno. What I do know is, developers just DO NOT write documentation (that eventually ends up in OpenAPI specs), and a "better alternative to OpenAPI" wouldn't solve that. For me at least, I write an API, and the tooling to generate the spec from that API is very good (happens automatically), and the tooling to generate the client from that API is reasonably good (CLI tooling), so "how good the spec is" isn't really relevant to me. What's relevant to me is how good the tooling is, and it's currently somewhere between "good enough" and "really quite good", while this guy's alternative tooling is "nonexistant".

[-]

heyheymonkey@reddit

Exactly. The schema is like an implementation detail of the tooling around creating reliable calls from clients to servers.

[-]

gredr@reddit

If you're reading or writing OpenAPI specs directly, either you're developing OpenAPI tooling, or you're doing something pretty wrong.

People had the same complaint about WSDL... but I say, if you cared about the WSDL contents themselves, that's a failing of the tooling, not the spec.

[-]

whkelvin@reddit (OP)

I've used Prisma as my ORM layer to interact with the database and I don't think writing the Prisma Schema is as annoying as writing the Open API Spec. What I am arguing here is that Open API Spec might not be the best option if I am trying to practice schema first design when building my APIs.

[-]

gredr@reddit

Why would you do that, though? I've never heard of anyone doing that.

[-]

whkelvin@reddit (OP)

The documentation aspect of open api is only a nice to have for me. The real value lies in code generation. If you generate the spec from your backend code and use the spec to generate client libraries, you might not have to look at the spec at all, but for those of us who prefer schema first design, it's very important to have a 'human friendly' spec that is easy to work with. Yes, my tooling is non-existent, but that's why I'm here. I am trying to make sure I'm not the only one dissatisfied with using Open API Spec to do schema first API design before I spend time building the actual tool. If I am the only one having difficulties, then perhaps this isn't a problem worth solving.

[-]

standing_artisan@reddit

Unfortunately, if you really want your open api spec to be exact, to include all kinds of things you have to write the raw yaml, especially if you want to use v3.

[-]

heyheymonkey@reddit

I guess it depends what you mean by “exact”. The OpenAPI annotations for Jersey give you a lot of control - at least as much as I need day to day.

And like another commenter said, the main thing is that you can generate clients reliably. There’s probably some amount of fudging you could allow that would get similar results in that regard.

[-]

12-idiotas@reddit

With blackjack and hookers?

[-]

gredr@reddit

One can only hope.

[-]

OurLordAndSaviorVim@reddit

Especially if he forgets about the OpenAPI replacement.

[-]

Weekly_Drawer_7000@reddit

GraphQL in a statically typed codebase that generates the schema from your types.

But if you need REST then just use OpenAPI. It’s fine.

[-]

ValuableCockroach993@reddit

I agree. Restful APIs are overrated.

[-]

me_again@reddit

CADL is worth a look.

https://devblogs.microsoft.com/azure-sdk/the-value-of-cadl-in-designing-apis/

[-]

remy_porter@reddit

Can we stop generating code. Please. Just write better abstractions.

[-]

OurLordAndSaviorVim@reddit

If you create better abstractions, someone will find a way to generate it so we do even less.

[-]

remy_porter@reddit

And you can replace the generation with yet better abstractions, creating a cycle where we endlessly do more with less.

Generating code is automating a solution in lieu of finding a better solution. It’s peak coder brain nonsense- I can automate a process so I’ll just do that instead of replacing the process with something better. Guaranteed tech debt before you even start.

[-]

whkelvin@reddit (OP)

I feel like we are in the era of code generation lol

[-]

remy_porter@reddit

We always have been. And it’s always been an anti pattern.

[-]

HolyPommeDeTerre@reddit

An article mostly about venting about frustration of open api spec. Which I can relate.

If you're looking for answers, there are none in the article.

Recently, I've been trying to do this exact thing, documenting our current api based on the code. We use Hapi as the http framework. Hapi allows validating the request and response using Joi. Joi allows for defining a very detailed schema. And also to put labels and descriptions. Which is very cool and practical.

There is a swagger plugin that generates dynamically the JSON. This plugin scans the routes and will take the request and response validation schema and generate the JSON. Great.

Now, two things:

we have a problem with streams. I want to stream (with back pressure) a very large JSON array of objects with limited memory. So my response is a stream of JSON serialized structures objects. I can define exactly what is contained in the stream with a schema but the validation schema can't. Which makes the validation fail. Couldn't find a way to bypass validation and still define the structure of the result. In the end, remove the validation, loose the documentation.
we are moving toward DDD and as such, we are validating parameters as part of a specific abstraction layer. Using a Joi alternative, Zod. Ok so now we want the schema validation to happen after the route has been triggered. So, I can't have validation at route or validation in the next layer won't ever be triggered. I still need a schema to be provided to the documentation by the route... So I need to define a non failing schema for the route and a failing one for the next layer... If I can find both versions.

The best approach I could find to this problem is to break the coupling and treat the API as a medium of communication. It has nothing to do else than register routes, document them and all the route handlers when it is appropriate. The next layer will register the route with all the documentation. So each time you update your parameters or response you update the registered parameters. From there, building the JSON is easy for the api. You don't couple your code and a tool of communication. You can be http or grpc or anything. It's just registering an entry point. If the entry point registering allows it, you can push the documentation associated.

[-]

thedevlinb@reddit

Zod. Ok so now we want the schema validation to happen after the route has been triggered. S

For Node projects using Zod, the typical path is types defined in Zod and then you use Zod's JSON Schema generating ability to output a schema. This does suck since you don't get a nice schema file you can share.

Alternatively, you define your types in TS, and then go from TS types to Zod and JSON Schema, there are some pretty good TS->JSON Schema compilers out there.

IMHO Typescript syntax should replace JSON Schema, it isn't as powerful (no regex checking, no range checking) but it is a lot simpler to write. As an alternative, JSON schema could adopt a TS like syntax as an alternative allowed syntax.

As it stands today, writing JSON Schema by hand is painful.

[-]