Как правильно писать документацию REST API?
Где писать документацию, в Google Docs, Markdown прям в репозитории или что-то еще - не важно, главное чтобы вам было удобно.
Важно чтобы эта документация была максимально полной и точной.
Как вариант можете посмотреть raml, если хочется специализированный формат.
мне очень нравится https://apiary.io/