May I say, look at SpyREST (SpyREST.com) if you consider developing the API firs...

sm_sohan on Jan 19, 2015 | parent | context | favorite | on: Ask HN: What's the best way to write an API spec?

May I say, look at SpyREST (SpyREST.com) if you consider developing the API first and then produce the documentation automatically simply by exercising the API? This is an open-source tool, feel free to take a look.

I'm developing SpyREST and will be happy to discuss if you want to learn more.