Hacker News Reader

Comment by lolinder | Hacker News Reader

The big weak point I've always seen in OpenAPI is that every change in the server needs to be mirrored in the spec. This opens up a lot of surface area for mistakes.

What I really want is a way to generate clients from the server source. I realize that this would require a highly opinionated web server with strong typing on all endpoints, but that just sounds like extra value to me.

Are there any web frameworks that enable generating clients like this, whether through a generated OpenAPI spec or otherwise?

View on HN

> Are there any web frameworks that enable generating clients like this, whether through a generated OpenAPI spec or otherwise?

I think perhaps you just never realized this has been common practice for a long time...

There are lots and lots of web service frameworks that do that: FastAPI in Python, Spring in Java, Play in Scala (iheartradio/play-swagger), rocket/okapi in Rust, many many more. You just need some introspection it's not a difficult thing to do.

I'm trying to go in this direction with an API I'm building at the moment in PHP: https://github.com/smolblog/smolblog-core/tree/feature/api-b... It uses a combination of definition-in-code (also used to translate the endpoint classes to the outside framework), reflection, and PHP annotations to generate the OpenAPI spec which I'm loading into Swagger to do testing.

Plenty of frameworks let you generate the spec from your server code. Nest.js is one off the top of my head. Generate the spec from your server code, version it in-repo, and write a test to run in CI that makes sure the spec is up to date with the code.

Something like:

https://ts-rest.com/

or https://github.com/sukovanej/effect-http ?

there are several others in TS world.

We're using tapir (https://tapir.softwaremill.com/en/latest/), and are pretty happy with it.

Django Rest Framework + drf-spectacular. It needs a couple tweaks here and there but it's great.

Apparently django-ninja (a different REST framework for Django) also generates an OpenAPI spec but I haven't tried it.

I've also had success with drf + drf-spectacular and then using the output OpenAPI spec to generate a typescript-react client with a third-party code generator.

It mostly just works, like you said, and almost acts as a framework guardrail: if the inferred client types are comprehensive and unsurprising then the view tends to be concise; a wonky type indicates there may be something nonstandard in the view that could be fixed by cleaner framework-abiding code.

There are various tools that will do some of this, utoipa [1] for rust and play-swagger [2] for scala + play that I've used in the past and enjoyed. They generate a significant portion of your spec for you, then a client can be generated from the spec.

[1] https://github.com/juhaku/utoipa

[2] https://github.com/iheartradio/play-swagger

I suspect OpenAPI advocates would argue you should start with the spec and use it to generate both the client and server. This is already a common pattern in other RPC definition languages such as gRPC. You _could_ write a server to match the gRPC spec, but why would you?

That works great if you're starting from scratch, but not so much if you're on a brownfield project. The way the generators are written, even generating a new endpoint can't be done after code has been written because it generates a whole file with route stubs.

Agreed, but if you’re asking for a solution that will generate a spec from your code, the more proven path is to generate code from a spec. Gives you more and costs less.

In my opinion the problem is that there’s some APIs that are impossible to represent with OpenAPI — that’s the real challenge they should be solving with this version, not reducing spec line count.

Not sure if I’m an advocate, but definitely a fan. I use frameworks (e.g., Django REST Framework, Nest.js) to build the server and generate my OpenAPI spec. I find it faster than writing YAML/JSON manually, and I end up with a half-working server at the end of it all.

It depends on your use case. Starting with the spec can unblock other implementers, so that they can work with mocks while you build the implementation. And it can help prevent re-work by describing the API first and getting feedback.

Bigger orgs also have style guides for public APIs and you can use various linters/standardization tools to enforce this. Tech writers can work on the API documentation without making changes in your code. There are tools that can tell you if your spec changes would cause breaking changes to API clients, such as adding a required query parameter.

You might not need these things on your project, but for some users it makes sense to write the spec first.

I’m familiar with all that. I worked at Stripe, where I started with a skeleton server first.

My point is, when I work with a framework that generates an OpenAPI spec, I find it faster to generate the spec from a prototype server than to write the spec by hand.

In addition to the many other solutions mentioned, Cloudflare can export an OpenAPI spec from the proxied traffic.

Optic/UseOptic does a similar traffic watch and spec export from local builds.

Reply on news.ycombinator.com