[angra_mainyu]

Basically my PoV. The API code itself is the best possible documentation.

Not to mention, how else do you see what complex logic might happen in an endpoint?

It seems typespec deals only with extremely simple CRUD APIs, for which again just reading the code would be good enough.

In scenarios where you want to offer the API consuming team some mock, I'd argue time would be better spent providing them with a a json-server implementation (see: https://www.npmjs.com/package/json-server).

[nicce]

If you can define single spec and autogenerate everything (client/server/OpenAPI et. al.), then spec first is superior.

Looking at https://smithy.io/2.0/index.html which can already generate much more than TypeSpec based on the docs and awesome list.

[darylteo]

Hmm. So as I understand it, it generates handler definitions which you then implement for typesafety but routing/hooking up is an implementation detail?

[angra_mainyu]

I'm not sure how I can autogenerate non-trivial logic, which is my point.

How would you handle a typical case where based on request data an endpoint fetches some additional information from various sources and depending on that performs several different actions?

This is the most common scenario I've encountered outside of extremely trivial CRUD endpoints.

EDIT: don't get me wrong, I'm not being purposefully obtuse - I was a big swagger advocate back in the day, however over time I came to realize that effort was much better invested in writing clear API code and possibly a mock impl like json-server.

[nicce]

I am still trialing Smithy, but as far as I understand, the code which is generated by Smithy, generates suitable abstractions and you never modify this code yourself.

It leaves the middleware library selection for the user, and with middleware you can do whatever more complex operations you need.

TypeScript server overview: https://smithy.io/2.0/ts-ssdk/introduction.html

> This execution flow allows the service developer to choose not only their endpoint, but the programming model of their service. For instance, all of the shim conversion and handler invocation can be refactored into a convenience method, or the service developer could choose to incorporate their favorite open source middleware library, of which the server SDK would simply be one layer. It also allows open-ended request preprocessing and response postprocessing to happen independent of Smithy. For instance, a developer could add support for request or response compression, or a custom authentication and authorization framework could be plugged into the application before the server SDK is invoked, without having to fight against a more heavyweight abstraction.

The Service type itself also seems to make it possible to define quite complex logic: https://smithy.io/2.0/spec/service-types.html

[shepherdjerred]

Smithy is _very_ similar to Coral (an internal library within Amazon).

Coral is used by every AWS service -- every AWS service defines their APIs using Coral, and if you want to interact with another service you use a generated client.

The client can generally be used as-is, though sometimes you might want some custom client code. In the case of a generated client you can just grab the API definition of the API you want to call, generate the client in the language of your choice, and... that's it!

For the server, you still have to implement the logic of how to form the responses, but what the request/responses look like it enforced by the framework.

Here's an example: https://gist.github.com/shepherdjerred/cb041ccc2b8864276e9b1...

I'm leaving out a _lot_ of details. Coral is incredibly powerful and can do a lot of things for you for free. Smithy is, from what I can see, the same idea.