Згенерований перелік ендпойнтів з параметрами - лише довідник. Розробник, що інтегрується з API, має відповіді на питання «з чого почати» і «що робити, коли щось пішло не так».
1. Швидкий старт: як отримати ключ, перший запит, який можна скопіювати й виконати за хвилину:
curl https://api.example.com/v1/vacancies?city=kyiv \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"
2. Автентифікація: як отримати й оновити токен, термін дії, області доступу (scopes).
3. Приклади - для кожного запиту й відповіді. Реалістичні дані, а не "string" і 0. В OpenAPI - поля example/examples у схемах і медіатипах. Кілька прикладів для різних сценаріїв (вакансія із зарплатою і без).
4. Помилки - не менш детально, ніж успіх:
- формат помилки (Problem Details чи власний) з прикладами;
- коди помилок бізнес-логіки й що з ними робити (
insufficient_balance- поповнити рахунок); - які помилки тимчасові й можна повторити (429, 503), а які ні.
5. Загальні правила API - один раз для всіх ендпойнтів:
- пагінація, фільтрація, сортування;
- формати дат, грошей, ідентифікаторів;
- ліміти частоти й заголовки, що їх показують;
- ідемпотентність і повтори;
- версіонування й політика змін.
6. Сценарії (гайди): типові задачі, що складаються з кількох запитів - «створити замовлення й оплатити», «синхронізувати каталог». Довідник ендпойнтів їх не пояснює.
7. Журнал змін (changelog) і дати застарівання.
8. SDK і колекції: офіційні клієнти, колекція Postman/Bruno, посилання на специфікацію OpenAPI для генерації власних клієнтів.
Якість, яку легко перевірити:
- новий розробник робить перший успішний запит без запитань до команди;
- кожен ендпойнт має приклад відповіді й перелік можливих помилок;
- приклади в документації перевіряються автоматично (контрактні тести, валідація за специфікацією) - інакше вони застаріють першими.
Інтерактивність: кнопка «спробувати» в документації (Swagger UI, Scalar, Stoplight Elements) з тестовим оточенням (sandbox) пришвидшує інтеграцію - але ніколи з продакшен-даними.
Докладніше в документації: Документація OpenAPI для початківців