OpenAPI generator for reactive data client?

[AndrewPrifer]

Hi, I’m evaluating rest-hooks for a new project. We already use OpenAPI/Swagger. Does it sound like a good idea to write an OpenAPI generator to transform the OpenAPI definitions into rest-hooks resource definitions? That way there’d be a single source of truth for all things API. Has anyone had a similar setup? Did it work? Do you think it could work? Thank you for your answers!

[ntucker]

This is a great idea! At Coinbase we generate our definitions from protos, which works great! Doing something similar for OpenAPI, would be great, and if you open source it - probably benefit many other people! We would happily link to such a generator in the docs, as we consider codegen the best way to work with APIs at scale.

The hardest part is probably creating the schema. Someone did some similar work on this for normalizr, which has an almost identical API https://github.com/eightcard/openapi-to-normalizr. This project might be helpful for any endeavors in this area.

[AndrewPrifer]

Thank you for the pointers @ntucker!

[jamakase]

@AndrewPrifer do you plan to implement it? I have some experience with https://github.com/OpenAPITools/openapi-generator and can probably help with the implementation of such a generator.

[AndrewPrifer]

@jamakase that’s great news! We are planning to make a generator! However after some thinking we decided to for now just start implementing the resource definitions by hand and see what we learn. We decided on this because of how flexible rest(-like) APIs can be. It’d of course be trivial to support neatly arranged resources that can be 1 to 1 translated to resource definitions that don’t override anything besides pk(), however more complex logic is required already for the common patterns of nested resources and server-side joins, which we already use. These probably don’t just mean a more complex generator but also necessary extensions to OpenAPI so that we can somehow communicate to the generator the intention.

If you already have a clear idea or prior experience with rest-hooks though, we’re always open to collaboration, it’s just that we’re still building up experience with it.

TLDR; we are absolutely planning to write a generator, but we’re taking some time to learn first.

[krunicn]

Hi @ntucker, would you mind sharing an overview on how you use protos to generate entities?

[ntucker]

@krunicn Sure! They key is identifying which messages are entities and then how they make a primary key. The easiest way to do this if you have control over your API is to simply designate a given field (like 'id') to always mean a primary. In this case, your codegen would simply check for existence of the field and if so create an Entity. Since they are all the same id, you can create an IDEntity base class to extend from.

Alternatively if you don't have that level of control, you can use the annotation system to specify the primary key.