Implement automatic API documentation for the LCD

[faboweb]

Summary

The Swagger REST documentation is updated manually and in 90% of the cases out of sync. Let's implement a process to updated the documentation automatically. I think we have this for Tendermint already.

Proposal

Investigate https://github.com/swaggo/swag by taking a simple module and adding annotations and generating a Swagger doc for it. If it works, perform this for all handlers and create the necessary scripts/CI tasks needed to automate and document it.

---

For Admin Use

• Not duplicate issue
• Appropriate labels applied
• Appropriate contributors tagged
• Contributor assigned/self-assigned

[fedekunze]

@faboweb it's being implemented on #2177

[faboweb]

Amazing!

[jackzampolin]

We are going with swagger documentation. The Bianje LCD PR implements this. #2199

[faboweb]

As far as I understand #2199 this is not a automatically generated documentation. Am I wrong?

[jackzampolin]

@faboweb That PR does have auto generated docs for the LCD implementation

[faboweb]

Then I didn't understand the PR correctly. I thought this just generates a visual documentation from a static swagger file. Feel free to close this issue if I am wrong.

[jackzampolin]

My understanding of the PR is that it generates the swagger file from the golang code using https://github.com/swaggo/swag. So this would be autogenerated documentation unless I'm misreading things...

[jackzampolin]

We have switched to swagger. I'm going to go ahead and close this issue.

[alexanderbez]

Reopening this issue (not sure why it was closed?). Taking a look at https://github.com/swaggo/swag this seems to be what we need. I haven't tested this yet, but ideally we'd annotate each handler and have some sort of script that gathers and generates a single doc file which we use.

@tnachen I see this as high priority because Swagger is often a big point for us in terms of keeping it up to date.

[alexanderbez]

Assigning this to myself and will be working on the handlers piecemeal.

[abelliumnt]

Before I created PR #2199, I had investigated https://github.com/swaggo/swag. At that time, swag tool has some defects. It can't generate right swagger yaml files if the data structure is too complicated, such as array of struct. So I had to choose a manual way to generate swagger yaml.
Now you'd better evaluate if these defects are still there.

[alexanderbez]

@HaoyangLiu do you have concrete examples? We are able to annotate return types that have arrays (e.g. validators)

[abelliumnt]

The main defects I found one years ago:

• Doesn't support array of struct
• Requires all handler must be locate in a root fold, which mean we have to refactor code structure.

Now if the above defects are solved or some defects are acceptable, then you can start to integrate swag with gaiacli

[alexanderbez]

Requires all handler must be locate in a root fold, which mean we have to refactor code structure.

This isn't true anymore I think. So far it works and we have handlers implemented in modules.

Doesn't support array of struct

Also not true anymore I believe.

That said, we are having some issues with the types being rendered. If you checkout #5038 and run make update-swagger-docs you'll get new results each time. Still debugging this one.

[tac0turtle]

gRPC swagger gen does this