ТЗ на рассматриваемый нами метод я также приложу в следующем сообщении.

Всё вышеописанное и мои примеры это лишь вариант того, как может быть описана документация на API.
Между проектами и даже командами всё очень сильно разнится. В каких-то командах господствуют разработчики, всё отталкивается от них и в этом случае как правило документация прописывается достаточно слабо, из разряда коммента в джире с текстом: "требуется разработать метод, который бы принимал на вход определенное количество параметров объекта user и сохранял его в БД". И на этом работа аналитика заканчивалась бы.
Есть наоборот команды, в которых "доминируют" аналитики и тогда задачи ставятся максимально чётко и подробно, прописываясь до каждой запятой так, чтобы разработчику не приходилось думать над алгоритмами и оставалось только перенести аналитический псевдокод в реальный (я всеми конечностями за этот вариант).

Всё это я сказал к тому, что скорее всего на ваших проектах вы не встретите именно такого описания и всё будет по своему. Поэтому главное это понять принцип того, как проектировать объекты, методы и как это всё работает внутри. А дальше вы сможете описать документацию в любом варианте, хоть двумя словами, хоть максимально подробно.

Если останутся вопросы, то милости прошу в комментарии.

P.S. Следующей темой разберу маппинг при интеграции back-to-back.