Создание 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 для переиспользуемых моделей, а не инлайним схему в каждый эндпоинт. Это критично при генерации клиентов — дублированные инлайн-схемы дают дублированные типы.
Интеграция в CI/CD
Спецификация живёт в git рядом с кодом. В pipeline добавляем два шага: spectral lint openapi.yaml проверяет соответствие правилам (нет операций без operationId, все ответы задокументированы), schemathesis run прогоняет fuzzing-тесты против staging-сервера. Если тест упал — PR не мержится.
Срок создания спецификации с нуля для API мобильного приложения: 1-2 недели в зависимости от количества эндпоинтов и наличия существующей документации.