Stream: beginners

Topic: OpenAPI


view this post on Zulip David (Dec 06 2023 at 13:01):

I'm wondering about how an open api implementation could be added - to document server APIs. I like the way NestJs does it with decorators, but for ROC an approach like open_api_spex seems a better fit (although elixir allows metaprogramming)

Or would this have to be added at the platform level?

view this post on Zulip LoipesMas (Dec 06 2023 at 23:13):

I think that without metaprogramming it might be hard to do that automatically. For example, in Python you can have decorator parse function name, arguments, return type and docstring to create full OpenAPI description. I bet the same is possible in Rust. Then, you don't have to write anything new or separate, just the standard type hinting and docs. I guess without metaprogramming there is no other choice than to register endpoints explicitly/manually. Platform could provide some helpers for that, but I'm afraid it wouldn't be able to do that automagically

view this post on Zulip Agus Zubiaga (Dec 07 2023 at 14:14):

Without decorators, you'd need a central place to register your handlers, but besides that I don't think you need any metaprogramming to have a really nice API in Roc.

view this post on Zulip Agus Zubiaga (Dec 07 2023 at 14:18):

For example, you can use Record Builders to define arguments to your endpoint and the library could automatically decode and validate those for you, while the compiler can make sure all the types line up.

view this post on Zulip Agus Zubiaga (Dec 07 2023 at 14:28):

A few months ago, I made this roc-gql experiment that allows you implement a fully type-safe and introspectable GraphQL backend without using any metaprogramming. You can see an example of a resolver definition here.

I'd imagine an OpenAPI package could use similar concepts, and it can probably look nicer as it wouldn't have to deal with the complexities of GraphQL.


Last updated: Jul 05 2025 at 12:14 UTC