If i am understanding your question correctly, your issue is that you've got API documentation that is hard to read/understand and is lacking in detail but you want to convert it into a more user friendly format that helps developers help themselves?
I would suggest looking at some of these API documentation tools. Some of them may have steep learning curves, but once you get use to them they will make your API's easy to use.
One thing to note about these tools, you can put lipstick on a pig but it is still a pig. Meaning, if you don't provide the content to these API's to make them more clear, your just trading one unclear/not developer friendly API document for another unclear/not developer friendly API document.
Swagger – The World's Most Popular Framework for APIs.[
^]
API Blueprint | API Blueprint[
^]
GitHub - lord/slate: Beautiful static documentation for your API[
^]