Привет!
Вчера меня попросили рассказать как правильно описывать API и рассказать про описание маппинга при вызове какого-нибудь метода. Обещал написать сегодня - пишу.
Обе темы на самом деле очень обширны и даже в часовую лекцию не сильно укладываются, но очень вкратце я постараюсь объяснить.
Начнем с описания API.

Представим, что вы уже знаете что это такое, знаете про REST, знаете про различные методы и вам нужно описать один из них.
Чтобы описать один из методов, допустим, микросервиса, аналитик должен написать документацию (паспорт микросервиса\api) для него и (опционально, необходимость зависит от проекта) swagger-спецификацию.

Допустим, вам необходимо описать метод, который создает объект User (например, мы разрабатываем функции регистрации пользователя в личном кабинете чего-нибудь).
Это будет метод POST /user.
Перед тем как приступать к написанию документации крайне желательно начать с описания модели данных (для этого даже разработали принцип DDD, кому интересно - загуглите).
Почему это следует сделать вначале? Потому что вам необходимо понимать следующее:
- Что это будет за объект?
- Какие у него будут атрибуты?
- Какой набор методов необходимо будет разработать для данного объекта помимо создания? Тут полезно почитать про концепцию CRUD, потому что как правило к каждому объекту необходимо предусмотреть и разработать все методы, чтобы им можно было управлять).

Поэтому возьмем базовый атрибутный состав для объекта User:
- id
- firstName
- lastName
- patronymic
- birthDate
- gender
- ...

Один из вариантов оформления документации на модель данных будет на первом скриншоте следующего сообщения.
После описания модели данных стоит приступить к написанию swagger-спецификации, если того требует проект (просто есть противоположный архитектурный подход, который гласит, что swagger может быть написан только разработчиком и только после окончания разработки, но никак не аналитиком. У этого подхода есть и плюсы и минусы).

Для понимания того, как писать сваггер нужно всего лишь ознакомиться с OpenAPI Specification v 2.0 или 3.0 (https://swagger.io/specification/). Ну либо взять пример, скопипастить (как делает большинство начинающих аналитиков) и уже по ходу дела разбираться почему так, а не иначе. Пример сваггера будет также в следующем сообщении конкретно для нашего метода POST /user.

Если ваш проект всё-таки предусматривает написание контракта, то почему его стоит писать первым, до документации? Ответ простой - если вы с кем-то интегрируетесь или наоборот с вами, то той команде достаточно получить только ваш контракт после чего они смело смогут приступать к разработке своей части. Ибо как конкретно ваш сервис работает внутри другим командам совсем не интересно, важно только то, как в него постучать и что они получат в ответ - а именно на эти вопросы и отвечает swagger. Следовательно это сильно ускоряет процесс разработки какой-нибудь кросс-функциональной фичи.

И последнее - вам нужно написать документацию непосредственно на то, как работает ваш метод внутри, после его вызова извне и до момента формирования ответа включительно. Если сложный метод, то это самая сложная и долгая часть.