Документування API

OpenAPI-специфікація

Стандарт опису REST API: openapi.yaml — шляхи, методи, схеми запитів/відповідей, коди помилок. Генерує: документацію (Swagger UI, Redoc), клієнти, моки, тести.

Мінімальна структура

info (назва, версія) → servers → paths (/users/{id}: get/post) → components/schemas (DTO-моделі) → security (bearerAuth). Пишіть специфікацію до коду — API-first.

Помилки

Документуйте всі коди: 400 валідація (з полями), 401/403, 404, 409 конфлікт, 429 rate-limit, 500. Формат помилки — один на весь API: {code, message, details}.

Версіонування

/v1/ в шляху — найпростіше і явно. Заголовок — для дрібних змін. Deprecation: заголовок Sunset + 6 міс на міграцію. Breaking change = нова версія, ніколи інакше.

Приклади

Кожен ендпоінт — з прикладом запиту і відповіді (реальними, не foo/bar). cURL-команда що працює copy-paste. Postman-колекція поруч зі специфікацією.

Changelog

API-changelog — окремий документ: нові ендпоінти, зміни схем, депрекації з датами вимкнення. Публікуйте разом з релізами, підписка для споживачів API.

Про документування API — OpenAPI і приклади

Документування API — OpenAPI і приклади — Структура openapi.yaml, коди помилок, версіонування, приклади запитів, changelog — як вести API-доки.. IT інструменти: TLS, API-доки, довідник. Використовуйте наші інструменти без реєстрації та встановлення програм. Усі обчислення відбуваються у вашому браузері — ваші дані не передаються на сервер.