Comment by dhruv3006

well - the point is. that we wanted to be standards compliant - and want to use existing technologies without actually reiventing a new standard or a proprietary format. (like some of the other api clients took).

and moreover we had this fundamental idea that documentation and testing should be in a single source of truth to avoid documentation drift (not just the spec drift).

And hence we came up with the idea of using markdown as the baseline and doing everything around it.