PRO шаблон описания REST-методов, который спасет от хаоса в API-документации📋

Каждый системный аналитик, на мой взгляд, рано или поздно сталкивается с задачей формирования или доработки шаблона описания, в частности, rest-метода. В интернете можно найти примеры таких шаблонов, но большинство из них являются только начальным приближением.

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

✅ Спецификация Swagger (OpenAPI) стал общепринятым для описания REST API, что делает его выбор логичным и практичным.

✅ Удобство для разработчиков и тестировщиков. Хорошо структурированное описание API в Confluence даёт возможность любому участнику команды, даже без глубоких знаний предметной области, быстро понять назначение и структуру метода.

✅ Возможность парсинга swagger в такой шаблон (об этом расскажу в следующих постах, подписывайтесь, чтобы не пропустить).

✅ Возможность использовать GPT-модели для генерации разных частей описания (об одном из таких примеров писал вот здесь https://t.me/pro_system_analysis/16).

Пример структуры шаблона

Как лучше всего организовать шаблон? 📑

1️⃣ Общая информация о методе

Описание метода – краткое пояснение, что делает этот метод.
URL и HTTP метод – указание на путь и тип запроса (GET, POST, PUT, DELETE и т.д.), иная информация, принятая для фиксирования в компании.

2️⃣ Параметры запроса

Указать в табличном виде для каждого входного параметра:

наименование,
тип параметра запроса (path, query и т.п.),
тип данных (boolean, string, object и т.п.),
ограничения (pattern, MaxIndex, MinLength и т.п.),
обязательность,
возможность принимать значение null
произвольный комментарий.

3️⃣ Параметры ответа

Указать в какой форме возвращается ответ;
Перечислить в табличном виде структуру ответа.

4️⃣ Примеры запроса и ответов

Пример запроса – привести пример реального запроса с параметрами и телом;
Примеры ответов – пример успешного ответа с примером структуры ответа и примеры негативных ответов с кодами 4хх/5хх (опционально).

5️⃣ Описание логики работы метода

порядок авторизации, в результате выполнения которого могут быть возвращены коды ответов 401 и 403,
валидации входных параметров (с учетом ограничений из раздела 2 и иные прочие проверки (например, условные), в результате которых может быть возвращён код ответа 400,
непосредственно саму логику работу метода: обращения к базам данных, выполнение вычислений, вызов методов других сервисов.

6️⃣ Диаграммы

блок-схемы,
sequence-диаграммы
другие принятые в компании графические артефакты.

В результате при обнаружении новых аспектов работы REST-методов, которые укладываются в спецификацию OpenAPI, которые не принимались во внимание на ранних стадиях документирования могут быть легко встроены в такой шаблон, например, учет Content-Type.

А что ты ещё бы добавил в такой шаблон? Какие элементы помогают твоей команде быстрее разобраться в API?

Поделись своим опытом в комментариях. 👇

Всем хорошего 🍁 понедельника и продуктивной недели!

Пойдёмте поработаем 👨🏻‍💻

made in: @pro_system_analysis