Как оформлять документацию для REST api?
OpenAPI. Некоторые фреймворки умеют это генерить автоматически. Вот пример.
У нас в команде пользуемся вот этим. https://apidocjs.com/ не знаю насколько удобно писать в этом документацию, но пользоваться ей удобно. Я правда не уверен в том что эта тулза актуальная.