Шаблон описания документации REST API и пример заполнения

Ниже приведен пример заполнения документации для REST API. Шаблон документа доступен для скачивания тут.

Забирайте чтобы использовать как отправную точку. Модифицируйте согласно своим потребностям. При заполнении ориентируйтесь на текст, приведенный ниже.

API-BAN-0001 Создание нового баннера

Метрики документа

Номер	API-BAN-0001
Название	Создание нового баннера
Последняя версия	1.0.0
Статус	Актуален
URL	POST api/v1/banners
Swagger	https://ovchinin.github.io/banners-api/#/banner/createBanner
Связанные документы	UC-0001, US-0001

Версия документа

Версия	Дата	Ответственный	Задача / требование	Изменения
1.0.0	25.09.2024	Иванов И.И.	№ 112233

1. Аутентификация

Для доступа к API требуется аутентификация. Используйте Bearer Token для аутентификации всех запросов. Токен передается в заголовке `Authorization`.

2. Адрес API (REST)

Prod:

Stage:

Test:

3. Описание метода

Метод для создания нового экземпляра баннера

4. Описание контракта API

4.1. Требования к интерфейсу API на вход

Код параметра	Тип данных	Обязательность	Описание	Доступные значения
HTTP-заголовки (headers)
X-B3-TraceId	String	да	Сквозной идентификатор запроса, для логирования
…
Поля тела запроса (body)
title	String	да	Заголовок баннера
mainText	String	нет	Основной текст баннера
image	String	да	Картинка
bannerCategory	String	да	Категория баннера	“Категория 1”, “Категория 2”, “Категория 3”
isVisible	Boolean	да	Признак видимости баннера
link	String	да	Ссылка на страницу с подробной информацией

4.2. Требования к интерфейсу API на выход

4.2.1 Успешное выполнение операции

Код ответа HTTP: 201

Запись успешно создана

Код параметра	Тип данных	Обязательность	Описание
HTTP-заголовки (headers)
X-B3-TraceId	String	да	Сквозной идентификатор запроса, для логирования
…
Поля тела ответа (body)
result	Object(Result)	да	Результат выполнения операции
data	Array(Data)	да	Полезная нагрузка ответа

Result

Результат выполнения операции

Код параметра	Тип данных	Обязательность	Описание
timestamp	String	да	Время выполнения запроса
status	Integer	да	Код ответа
service	String	да	Сервис, ответственный за метод
message	String	да	Сообщение

Data

Полезная нагрузка ответа

Код параметра	Тип данных	Обязательность	Описание
id	String	да	Идентификатор баннера
title	String	да	Заголовок баннера
mainText	String	нет	Основной текст баннера
image	String	да	Картинка
bannerCategory	String	да	Категория баннера
isVisible	Boolean	да	Признак видимости баннера
link	String	да	Ссылка на страницу с подробной информацией

4.2.2 Неуспешное выполнение операции

Формат ответа

Код параметра	Тип данных	Обязательность	Описание
HTTP-заголовки (headers)
X-B3-TraceId	String	да	Сквозной идентификатор запроса, для логирования
…
Поля тела ответа (body)
result	Object(Result)	да	Результат выполнения операции
data	Array[ ]	да	Полезная нагрузка ответа

5. Обрабатываемые ошибки

HTTP-код	Описание
400	Указаны некорректные параметры запроса
404	Ресурс не найден
500	Внутренняя ошибка сервера

6. Пример запроса / ответа

6.1. Запрос


{
  "title": "Заголовок баннера",
  "mainText": "Основной текст баннера",
  "image": "https://example.com/banners/banner1.jpg",
  "bannerCategory": "Категория 1",
  "isVisible": true,
  "link": "https://example.com/banners/banner1"
}

6.2. Успешный ответ


{
  "result": {
    "timestamp": "2021-04-25T21:30:05+03:00",
    "status": 200,
    "service": "banners",
    "message": "Запрос выполнен успешно"
  },
  "data": [
    {
      "id": 1,
      "title": "Заголовок баннера",
      "mainText": "Основной текст баннера",
      "image": "https://example.com/banners/banner1.jpg",
      "bannerCategory": "Категория 1",
      "isVisible": true,
      "link": "https://example.com/banners/banner1"
    }
  ]
}

6.3. Ответ с ошибкой


{
  "result": {
    "timestamp": "2021-04-25T21:30:05+03:00",
    "status": 400,
    "service": "banners",
    "message": "Указаны некорректные параметры запроса"
  },
  "data": []
}

7. Сопоставление параметров метода с базой данных

Параметр метода	Параметр БД	Комментарий
id	banner.id	UUID. Генерируется автоматически
title	banner.title
mainText	banner.main_text
image	banner.image
bannerCategory	banner.banner_category
isVisible	banner.is_visible	Значение по умолчанию true
link	banner.link