Почему некоторые запросы пишутся руками, некоторые через Swagger?

Почему запросы пишутся вручную vs Swagger: за и против

Отличный вопрос о документировании API. В моей практике я использую оба подхода в зависимости от контекста.

Что это вообще: Ручные запросы vs Swagger

Ручные запросы:

• CURL, Postman, REST Client
• Документируешь вручную
• Примеры в README, Wiki

Swagger (OpenAPI):

• Автоматическая документация
• JSON/YAML спецификация
• Интерактивный UI
• Генерирование кода клиентов

Когда я пишу ручные примеры (CURL)

1. Когда документирую requirement (как BA)

Я пишу пример для разработчика - это быстро, без overhead.

Преимущества:

• Быстро реализовать
• Разработчик сразу видит примеры
• Легко включить в Requirements
• Не требует генерирования

Когда это подходит:

• Документирование требований (BA → Dev)
• Быстрые примеры
• Когда нет строгого API contract
• Внутренние инструменты

Когда я использую Swagger/OpenAPI

1. Для публичного API (SaaS, Platform)

Если API используется клиентами извне - нужна стабильность и документация.

Преимущества:

• Единый источник истины
• Генерируется интерактивный UI
• Клиенты видят документацию
• Можно генерировать SDK
• Type safety

Когда это подходит:

• Публичные API
• Много клиентов (10+)
• Нужна стабильность контракта
• Нужна типизация

Реальный пример из моей практики

Проект: Платформа для микрокредитов

Было 3 типа API:

1. Внутреннее API (Microservices)

Ордер Service → Payment Service → Notification Service

Документировал CURL примеры в README.

Почему? Быстро, разработчики в одной команде, часто меняется, не нужна строгая типизация.

2. Публичное API (для партнеров)

Партнеры интегрируют платежи в свои системы.

Использовал OpenAPI/Swagger с Swagger UI интерфейсом.

Почему? Много клиентов, нужна стабильность, нужна документация, нужна типизация.

3. Admin API (внутреннее, но комплексное)

Админы управляют платежами, users, reports.

Использовал смешанный подход: OpenAPI + CURL примеры + GraphQL для больших запросов.

Как выбрать подход: мой checklist

Использовать CURL примеры, если:

• API внутреннее (микросервисы)
• Клиенты - разработчики одной компании
• API часто меняется
• Нужно быстро документировать
• Простые endpoints (5-10)
• Документ - Requirements

Использовать Swagger/OpenAPI, если:

• API публичное
• Много внешних клиентов
• Нужна стабильность контракта
• Нужно генерировать SDK
• Много endpoints (20+)
• Нужна типизация
• Нужна версионирование

Гибридный подход (лучший)

Оптимально комбинировать:

1. BA документирует требование (CURL пример)
2. Dev реализует
3. Dev генерирует Swagger из кода
4. Swagger UI для клиентов
5. Документация обновляется автоматически

Процесс работы

Этап 1: BA документирует (CURL примеры в requirements)

Business Analyst пишет требование с примером.

Этап 2: Dev реализует и добавляет Swagger annotations

Разработчик реализует с docstrings для генерирования документации.

Этап 3: Swagger генерируется автоматически

Systems автоматически создают Swagger UI и OpenAPI spec.

Когда конфликты

Проблема: Swagger не совпадает с реальностью

Решение: Automated tests

Тесты проверяют что API соответствует Swagger спецификации.

Вывод

Нет одного правильного подхода.

CURL примеры:

• Лучше для внутренних API
• Быстро документировать
• Гибко менять

Swagger/OpenAPI:

• Лучше для публичных API
• Единый источник истины
• Типобезопасность
• SDK генерирование

Лучший подход:

1. BA документирует CURL примеры
2. Dev реализует с Swagger annotations
3. Swagger генерируется автоматически
4. Документация синхронна с кодом
5. Тесты проверяют соответствие

Так получаешь лучшее из обоих подходов: гибкость + консистентность.