Створення Swagger/OpenAPI-специфікації для API мобільного додатка
OpenAPI-специфікація — це контракт між мобільним клієнтом та сервером. Без неї кожна зміна бекенда потенційно ломає додаток, і дізнаєшся про це тільки в момент краху у користувача.
Чому YAML-файл у репозиторії важливіший, ніж вики-сторінка
Специфікація OpenAPI 3.1 — машиночитаний документ. З неї автоматично генеруються: TypeScript-типи для React Native через openapi-typescript, Kotlin-клієнт через openapi-generator, Swift-клієнт через CreateAPI або swift-openapi-generator від Apple. Вики-сторінка такого не умітаре.
Ще одна перевага: contract testing. Інструменти на кшталт Dredd або Schemathesis беруть специфікацію та перевіряють, що реальний сервер їй відповідає. Це ловить регресії на бекенді до того, як мобільна команда дізналась про зміни.
Як будуємо специфікацію
Якщо бекенд на 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 для переиспользуємих моделей, а не інлайним схему в кожен endpoint. Це критично при генерації клієнтів — дублювані інлайн-схеми дають дублювані типи.
Інтеграція у CI/CD
Специфікація живе в git рядом з кодом. У pipeline додаємо два кроки: spectral lint openapi.yaml перевіряє відповідність правилам (немає операцій без operationId, всі відповіді задокументовані), schemathesis run прогоняє fuzzing-тесты проти staging-сервера. Якщо тест упав — PR не мержиться.
Терміни створення специфікації з нуля для API мобільного додатка: 1-2 тижні залежно від кількості endpoints та наявності існуючої документації.