Шаблон описания документации 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 |
Другие шаблоны
Шаблон документации API для JSON-RPC и образец заполнения опубликованы тут
Может быть у вас есть примеры шаблонов получше?
Опубликовано 22 октября 2024
Просмотров: 1170
Вместо комментариев