I may be misunderstanding some things, but reading some of the code I noticed that the API spec is defined using protobuf, and the generated types are used in the controllers.
I also guess that the generated OpenAPI spec, was generated from the protobuf files, and is used to generate the API docs.
My question is, any particular reason for this approach?
You hit on a lot of it – using protobuf as a base allows for a lot of autogeneration on top, both in terms of tools that exist, and also in terms of tools that don’t exist! For instance, nearly our entire Go SDK is autogenerated via https://github.com/hashicorp/boundary/tree/main/internal/api/genapi by using protobuf reflection.
Because we can map between JSON and protobuf very easily by ensuring we are using a specific subset of protobuf capabilities, this gave us the ability to get a lot of generation and functionality as a baseline while still supporting JSON for our public API.
I had a similar idea in mind a while ago, but thought it may be an overkill.
I guess writing specs in protobuf is way easier then handwrite them in json. Good point on using protobuf reflection for the SDK generation.
Thank you for your fast answer, and for the great products you guys are building - much appreciated
No problem! Glad this helped!