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


Главная / Шаблоны

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

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


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

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

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

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

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

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

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

2. Адрес API (REST)

Prod: 

Stage:

Test: 

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

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

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

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

Код параметраТип данныхОбязательностьОписаниеДоступные значения
HTTP-заголовки (headers)
X-B3-TraceIdStringдаСквозной идентификатор запроса, для логирования
Поля тела запроса (body)
titleStringдаЗаголовок баннера
mainTextStringнетОсновной текст баннера
imageStringдаКартинка
bannerCategoryStringдаКатегория баннера“Категория 1”, “Категория 2”, “Категория 3”
isVisibleBooleanдаПризнак видимости баннера
linkStringдаСсылка на страницу с подробной информацией

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

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

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

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

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

Result

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

Код параметраТип данныхОбязательностьОписание
timestampStringдаВремя выполнения запроса
statusIntegerдаКод ответа
serviceStringдаСервис, ответственный за метод
messageStringдаСообщение

Data

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

Код параметраТип данныхОбязательностьОписание
idStringдаИдентификатор баннера
titleStringдаЗаголовок баннера
mainTextStringнетОсновной текст баннера
imageStringдаКартинка
bannerCategoryStringдаКатегория баннера
isVisibleBooleanдаПризнак видимости баннера
linkStringдаСсылка на страницу с подробной информацией

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

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

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

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. Сопоставление параметров метода с базой данных

Параметр методаПараметр БДКомментарий
idbanner.idUUID. Генерируется автоматически
titlebanner.title
mainTextbanner.main_text
imagebanner.image
bannerCategorybanner.banner_category
isVisiblebanner.is_visibleЗначение по умолчанию true
linkbanner.link

Другие шаблоны

Шаблон документации API для JSON-RPC и образец заполнения опубликованы тут

Может быть у вас есть примеры шаблонов получше?

Над статьей работали