@saurabh & @ayesh, hopefully you’re seeing conversations like this one. I would recommend focusing on the human-readable content & examples (the content we don’t get from a tool like Swagger), assuming we will eventually want to combine this content with auto-generated information from our code (or even move this content into the code so full documentation can be auto-generated).
In other words, I would not spend a lot of time manually generating what can be automatically generated from code using tools like Swagger; rather, focus on the information a developer needs to effective understand & use the API. Ultimately, we’d like to be able to merge human written documentation and auto-generated documentation that is relatively easy to keep in synch with the code and goes beyond a simple enumeration of resources with little guidance on how/why/when to use them.