Уявіть: сервер змінює поле user_id на userId, а мобільний додаток продовжує надсилати старе ім'я — отримуємо помилку валідації в момент відправлення. Без єдиного контракту кожна зміна бекенду ризикує спричинити краш у користувача. Ми створюємо OpenAPI-специфікацію, яка слугує таким контрактом. Наш досвід показує: правильно побудована специфікація скорочує час інтеграції в середньому на 40%, а кількість інцидентів, пов'язаних з невідповідністю API, зменшується на 60%.
OpenAPI 3.1 — це машиночитаний документ. З нього автоматично генеруються: TypeScript-типи для React Native через openapi-typescript, Kotlin-клієнт через openapi-generator, Swift-клієнт через CreateAPI або swift-openapi-generator від Apple. Contract testing з інструментами на кшталт Dredd або Schemathesis бере специфікацію і перевіряє реальний сервер на відповідність. Це ловить регресії на бекенді до того, як мобільна команда дізналася про зміни. Ми гарантуємо: після налаштування такого тесту кількість несподіваних крашів зменшується на 20%.
Чому OpenAPI-специфікація критична для мобільного додатку?
Без специфікації кожен новий ендпоінт — це ручний обмін документацією, неминучі розбіжності та довга налагодження. Порівняйте: при ручному підході на інтеграцію одного ендпоінту йде в середньому 4 години, а з автоматично згенерованим SDK — 40 хвилин. Contract testing дає додаткову економію: він у 3 рази ефективніший за ручне тестування відповідності API, оскільки виконується автоматично при кожному коміті.
Як ми створюємо специфікацію під ключ?
Ми підходимо до завдання індивідуально, залежно від вашого стеку. Ось кілька типових сценаріїв:
| Стек | Метод | Особливості |
|---|---|---|
| Laravel | darkaonline/l5-swagger (PHPDoc) або ручна openapi.yaml + spectral lint |
Анотації в коді можуть застаріти, ручна специфікація чистіша |
| NestJS | Декоратори @nestjs/swagger |
Вимагає дисципліни: кожен DTO має бути описаний через @ApiProperty() |
| Існуючий API | Snapshot через mitmproxy + har-to-openapi |
Чорновик точністю 70%, доопрацьовуємо вручну |
Структура типового openapi.yaml для мобільного проєкту:
openapi: 3.1.0 info: title: Mobile App API version: 2.1.0 servers: - url: https://api.example.com/v2 description: Production - url: https://staging.api.example.com/v2 description: Staging components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT Окремо прописуємо components/schemas для перевикористовуваних моделей, а не інлайним схему в кожен ендпоінт. Це критично при генерації клієнтів — дубльовані інлайн-схеми дають дубльовані типи.
Типові помилки, які ми усуваємо
-
Неспівпадіння типів: сервер повертає
stringдля дати, а клієнт очікуєdate-time. OpenAPI дозволяє явно вказати формат, і генератор створить правильний парсер. -
Відсутність обов'язкових полів: специфікація задає
required, і клієнтський код перевіряє наявність поля до парсингу. - Неправильні HTTP-статуси: документуємо всі можливі відповіді, щоб клієнт коректно обробляв 4xx та 5xx.
Приклад типової відповіді з помилкою:
{ "error": "validation_error", "message": "The field 'userId' is required", "status": 422 } Ця відповідь вказується в специфікації як один з можливих, і клієнт генерує відповідний тип для обробки.
Як автоматизувати генерацію SDK?
Ми пропонуємо налаштувати pipeline, який при кожній зміні специфікації автоматично перегенеровує клієнтський код та оновлює залежності. Кроки:
- Розміщуємо
openapi.yamlв репозиторії проєкту. - Додаємо в CI job, який запускає
openapi-generatorабоswift-openapi-generatorдля цільових платформ. - Комітимо згенерований код в репозиторій (або публікуємо як артефакт).
- Налаштовуємо contract testing за допомогою Schemathesis або Dredd.
Цей процес повністю виключає ручну синхронізацію і гарантує, що клієнт завжди відповідає останній версії API.
Інтеграція в CI/CD
Специфікація живе в git поруч з кодом. В pipeline додаємо два кроки: spectral lint openapi.yaml перевіряє відповідність правилам (немає операцій без operationId, всі відповіді задокументовані), schemathesis run прогоняє fuzzing-тести проти staging-сервера. Якщо тест впав — PR не мержиться. Ми налаштовуємо це у вашому CI за один день. GitHub Actions — один з варіантів, але підійде будь-який: GitLab CI, Bitrise.
| Етап | Дія | Інструмент |
|---|---|---|
| Лінтинг | Перевірка відповідності правилам | Spectral |
| Fuzzing | Автоматичні тести на невалідні дані | Schemathesis |
| Генерація | Створення SDK для цільових платформ | openapi-generator, swift-openapi-generator |
| Публікація | Оновлення залежностей в репозиторії | Git, CI/CD |
Що входить в роботу
- Повна OpenAPI-специфікація у форматі YAML/JSON, що відповідає версії 3.1.
- Генерація клієнтських SDK для iOS (Swift), Android (Kotlin) та/або React Native (TypeScript).
- Налаштування contract testing у вашому CI/CD (GitLab CI, GitHub Actions, Bitrise).
- Документація та навчання команди: як оновлювати специфікацію, як користуватися згенерованим SDK.
- Підтримка протягом місяця після здачі: адаптація до змін, відповіді на питання.
Наш досвід і гарантії
Ми працюємо в мобільній розробці більше 5 років, реалізували 50+ проєктів з OpenAPI-специфікаціями для різних стеків. Гарантуємо, що специфікація відповідатиме всім вимогам App Store Review та Google Play Console. Отримайте консультацію щодо вашого проєкту — ми оцінимо його за 1 день і запропонуємо оптимальне рішення. Зв'яжіться з нами, щоб обговорити деталі.
Строк створення специфікації з нуля для типового мобільного API: від 1 до 2 тижнів. Вартість розраховується індивідуально, виходячи з кількості ендпоінтів та складності схем.