Я считаю что REST APi должен очень простым и понятным, но действительно сложными представлениями я пока не рулил.
В качестве доки я обычно даю минимальный пример взаимодействия в котором комментирую необходимые действия и привожу должные ответы от сервиса. В принципе наверно можно найти тулзу которая приведет код примера к красивому html, но это скорее вопрос генерирования док вообще а не для api.
