[martinn]

Could someone clarify what's the use case of a tool like this please.

Is this something that helps if you, say, are building a new API and will need to create both the server implementation as well as the client implementations in multiple languages? And so, it can automatically do all of that for you based on an API spec? Or is it something different.

Funnily enough, I developed a Python library recently that allows you to build API clients in a way that very closely resembles the TypeSpec example. But I'm pretty sure they are very different things.

[wg0]

If you are in a situation where you have a backend and you want to expose an API and then you would eventually want a client, you would need format specs as the starting point where server and clients are generated from that one source.

At the moment, OpenAPI with YAML is the only way to go but you can't easily split the spec into separate files as you would do any program with packages, modules and what not.

There are third party tools[0] which are archived and the libraries they depend upon are up for adoption.

In that space, either you can use something like cue language 1] or something like TypeSpec which is purpose built for this so yet, this seems like a great tool although I have not tried it yet myself.

[0]. https://github.com/APIDevTools/swagger-cli

[1]. https://cuelang.org/

EDIT: formating

[martinn]

Thanks, that makes sense for that use case.

My question is probably a more general one around the use case for writing an API spec (in a format like OpenAPI or TypeSpec), and then translating and writing the server implementation to match that. As opposed to being able to create the API spec automatically based on server implementation (and being able to easily refresh it).

Understand that writing the spec and then the server implementation seems to have some benefits. I'm curious to hear about the common use cases for it, as in my mind I could quickly stub a server implementation (and automatically generate a spec) rather than try to create the spec by hand and then write the server implementation again. But I'm sure there's some other things I'm missing.

[wg0]

No, you don't have to write the server stub yourself. You should generate it.

See my comment below to another question [0]

That's the upside that instead of generating specs from comments of methods, you actually generate the methods from the formally verified/linted and crafted spec.

[0]. https://news.ycombinator.com/item?id=40208847

[mnahkies]

Whilst it's not as expressive/flexible as typespec, and in my experience it's not always well supported by tooling, you can do $ref's across files in openapi specifications.

Eg: https://github.com/mnahkies/openapi-code-generator/blob/main...

[monkfish328]

So just to clarify, how would one go about auto-generating a stub handler for these route definitions?

[wg0]

One such that i know of is oapi-codegen[0] for Go. Highly recommended. And for Typescript, I think it is hard to beat Open API Typescript [1]

[0]. https://github.com/deepmap/oapi-codegen

[1]. https://openapi-ts.pages.dev/