Explore options to version API docs and tie them to our repos

[ChrisSchinnerl]

Adding this to this repo since it's really relevant to all of our node repos.

With v2.0 around the corner we should improve our process for API documentation a bit. Ideally we'd tie our documentation to commits in our repos. Meaning that the same PR that changes a route also adds the documentation for it. Which should improve the quality of our docs overall. Also it would be cool if users had the option to pick a specific version of our API in the docs.

It seems like prometheus has support to link an API to a repo by checking in an openapi spec and the collection. So we should perform some research to see if that is a viable option for our APIs.

[alexfreska]

@ChrisSchinnerl ideas:

• We could annotate endpoints with something like: https://github.com/swaggo/swag
• Looks like GitBook supports auto generating API documentation from a swagger/openapi spec: https://www.gitbook.com/solutions/api

[ChrisSchinnerl]

I think Postman also lets us generate API documentation from an openapi spec. The tricky part I think is finding a nice way for devs to keep it updated. But the swaggo annotations look pretty promising if we can just keep them right next to our go routes.

@n8maninger any thoughts on Go swag? I think you said you used swagger before.

[n8maninger]

I’m heavily against annotations in code. Other than that no real preference.