Improve API docs

[jennijuju]

Well, we know what this is about 😀 The docgen generated api docs is not good enough, we want something that shows real request examples and responses, and comments on what does the fields mean.

[jennijuju]

one option is to have it in postman

[dineshshenoy]

Potentially swagger is a good option here?

[jennijuju]

@magik6k and @whyrusleeping suggested that we can add more stuff to docsgen:

• More real/mae-sense data to generate example
• run it against the node and generates sample output
• generate curl example

[dineshshenoy]

Maybe we can breakup this task into three components:

1. Using swagger or a related docs framework to define the schema and generate a swagger.json file (infrastructure)
2. Add annotations to our existing docs to match with the schema for Initial structure lotus#1 - the more tedious aspect
3. Add a rich UI layer from the swagger.json (lots of potential like readthedocs.io, RST, Postman, etc)