Generate rest api via OpenAPI

[gianarb]

I had a chat with @kdeng3849 about OpenAPI and my transformation from a code generator hater to its fun because doing API requires a lot of code that is actually kind of boring not that maintainable manually written.

I had the opportunity to work on two projects one after each other, both where using swagger.yaml but only one was generating the code out from it. The one that generated the code was very much a pleasure to work with.

You get documentation for free, your documentation is always in line with the code. You can generate a baseline for SDKs. It is much easier to get a consistent flavor compared with the hands written one. At least from my experience.

She quickly tried to do it starting from our proto https://github.com/kdeng3849/tink/tree/open-api/protos but she got stuck along the way and she asked me to open an issue to discuss it publicly. (@kdeng3849 if you can add a bit more context it will be great).

here it is!

[kqdeng]

Sorry for only getting back to this now, but I've been making some changes to the REST api (#197), where I am now creating all the rest endpoint handlers manually (and not using the generated gateway files). The reason for this change was that the generated code does not allow for as much customization as we would have liked, and as a result, there is now a discrepancy between the generated swagger.json files and how it actually works (input/output data, formatting, etc.)
So at its current state (or at least after my PR gets merged), I don't think using OpenAPI will still work to allow for effortless, up-to-date docs as originally intended.

I can still generate the swagger.json files as a reference and something to work off of. I actually was able to keep the unused, obsolete fields from appearing in the jsons (it's the second blocker from what I mentioned in our chat), but there is still 3 separate json files that would have to be woven together.

[gianarb]

Based on my experience the OpenAPI workflow is comfortable when it is used to generate docs, models, clients, and so on. As soon as one of those bits is lost the situation easily gets out of control. But if it does not feet our needs I presume the game is over 😁 😁

Do we need the REST API? From my understanding, GRPC can be used client-side as well

https://pace.dev/blog/2020/02/26/tech-stack-at-pace.html (section "Services: Should I use REST or RPC?")

Thank you for trying it!

[kqdeng]

Yeah no problem.
The original motivation for creating the rest api was so our central api could hit it, but it also serves as another way for users to interact with tink without being language specific.

I was thinking we could still use the swagger.json files as a base, since I don't expect the api to be rapidly changing or growing. But yeah, it wouldn't be using OpenAPI and it'll be written/maintained manually.

[gianarb]

NOt needed for now