Consider using swagger for API self-description
mydatascience opened this issue · 2 comments
It will be great if a user can use the nice web-API via swagger-UI for the ADAM controller. Makes it much easier to use, especially remotely. Go-Swagger module https://github.com/go-swagger/go-swagger
Adam implements two sets of API end points:
- EVE controller APIs https://github.com/lf-edge/eve/blob/master/api/API.md
- Adam admin APIs
Given that №1 is all in proto definitions I can see us generating swagger specs by simply running protoc --swagger_out=... AND we potentially can express №2 in proto as well (although I don't know if @deitch will look at it is more of an overkill).
Then, I suppose, it is simply a question of https://goswagger.io/usage/serve_ui.html
Yes, I think this is a good idea. Honestly, my biggest beef with swagger has always been the overhead. You have to have structs you can annotate, which now means maintaining it both in the main location where the routes actually are implemented, in this case here, and in the docs dir or wherever you annotate them. That means you're actually defined in two places, and is guaranteed to get out of sync.
That doesn't mean it isn't the "right thing to do" (it might be), just that it is a pain to do once, and a pain to maintain. We now need to move from the simple handler above to something much more complex.
Is it worth it? If so, I am more than happy to take a PR for it.