Как вы использовали Swagger (OpenAPI) в своих проектах?

Я использовал Swagger (OpenAPI) как центральный инструмент для проектирования, документирования, тестирования и согласования API между фронтенд- и бэкенд-командами.

Конкретный пример интеграции в PHP-проекте (Laravel + darkaonline/l5-swagger):

1. Установка и настройка: После установки пакета спецификация генерируется из аннотаций PHP-Doc.
2. Описание endpoint'а:

   /**
    * @OAGet(
    *     path="/api/v1/users",
    *     summary="Получить список пользователей с пагинацией",
    *     tags={"Users"},
    *     @OAParameter(
    *         name="page",
    *         in="query",
    *         description="Номер страницы",
    *         required=false,
    *         @OASchema(type="integer", default=1)
    *     ),
    *     @OAResponse(
    *         response=200,
    *         description="Успешный ответ",
    *         @OAJsonContent(
    *             type="object",
    *             @OAProperty(property="data", type="array", @OAItems(ref="#/components/schemas/User")),
    *             @OAProperty(property="meta", ref="#/components/schemas/PaginationMeta")
    *         )
    *     ),
    *     @OAResponse(response=401, description="Не авторизован"),
    *     security={{"bearerAuth": {}}}
    * )
    */
   public function index(UserIndexRequest $request)
   {
       return UserResource::collection(User::paginate(20));
   }

3. Определение схем (DTO) и повторного использования:

   /**
    * @OASchema(
    *     schema="User",
    *     required={"id", "name", "email"},
    *     @OAProperty(property="id", type="integer", example=1),
    *     @OAProperty(property="name", type="string", example="John Doe"),
    *     @OAProperty(property="email", type="string", format="email", example="john@example.com"),
    *     @OAProperty(property="created_at", type="string", format="date-time")
    * )
    */
   class UserResource extends JsonResource { /* ... */ }

Как это использовалось на практике:

• Договорённость (Contract First): Фронтенд-разработчики начинали работу по готовой спецификации (swagger.json), не дожидаясь реализации всех endpoint'ов. Генерировали клиентские SDK с помощью swagger-codegen.
• Автоматическая документация: По адресу /api/documentation всегда была актуальная интерактивная документация Swagger UI.
• Интеграционное тестирование: С помощью swagger-php и phpunit писались тесты, которые проверяли, что реальные ответы API соответствуют задекларированным схемам.
• Валидация запросов: Входящие запросы автоматически проверялись на соответствие спецификации (типы данных, обязательные поля).

Итог: Swagger превратил документацию из отстающей обязанности в живой, полезный артефакт, который ускорил разработку и снизил количество ошибок при интеграции.