Что такое Swagger?

Что такое Swagger

Swagger (теперь официально называется OpenAPI) — это спецификация и набор инструментов для описания, документирования и тестирования REST API. Для фронтенд-разработчика Swagger важен как источник истины о том, какие endpoints доступны и как их использовать.

История и эволюция

• Swagger — оригинальное название и спецификация (создана в 2010)
• OpenAPI 3.0 — переименованный стандарт, принятый Linux Foundation (2017)
• OpenAPI 3.1 — текущая версия со множеством улучшений

Термины используются как синонимы, но "OpenAPI" — это новое официальное имя.

Основное назначение для фронтенда

Swagger/OpenAPI описывает API в структурированном виде:

openapi: 3.0.0
info:
  title: PrepBro API
  version: 1.0.0
  description: API для платформы подготовки к IT-собеседованиям

servers:
  - url: https://api.prepbro.ru/api/v1
    description: Production
  - url: http://localhost:8000/api/v1
    description: Development

paths:
  /users/{userId}:
    get:
      summary: Получить пользователя
      description: Возвращает информацию о пользователе по ID
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: Пользователь не найден
        '401':
          description: Не авторизован

Преимущества Swagger для фронтенда

1. Автоматическая генерация документации

Вместо того чтобы искать docs в README или Confluence, все в одном месте:

# Swagger UI доступен по адресу
https://api.prepbro.ru/docs

# RedDoc альтернатива
https://api.prepbro.ru/redoc

Визуальный интерфейс показывает:

• Все endpoints
• Параметры запроса
• Примеры запросов и ответов
• Коды ошибок
• Схемы данных

2. Генерация клиентов

Лучший инструмент для фронтенда — openapi-generator:

# Генерируем TypeScript клиент из спецификации
npm install @openapitools/openapi-generator-cli

npx openapi-generator-cli generate \
  -i https://api.prepbro.ru/openapi.json \
  -g typescript-axios \
  -o ./src/api/generated

Результат — полностью типизированный клиент:

// Автогенерированный клиент
import { UsersApi } from './api';

const usersApi = new UsersApi();
const user = await usersApi.getUser('user-id');
// user полностью типизирован!

3. Валидация данных на лету

Dynamic imports не требуются — Swagger UI позволяет тестировать API прямо из браузера:

// Не нужно писать curl, используем UI
// 1. Открываем https://api.prepbro.ru/docs
// 2. Находим endpoint /users/{userId}
// 3. Вводим параметры
// 4. Нажимаем "Try it out"
// 5. Видим response

Типичный workflow с Swagger

Шаг 1: Бэкенд описывает API в спецификации

# FastAPI пример (автогенерирует Swagger)
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(
    title="PrepBro API",
    version="1.0.0",
    docs_url="/docs",
    openapi_url="/openapi.json"
)

class User(BaseModel):
    id: str
    name: str
    email: str
    role: str

@app.get("/api/v1/users/{user_id}", response_model=User)
async def get_user(user_id: str):
    """Получить пользователя по ID"""
    return {"id": user_id, "name": "John", "email": "john@example.com", "role": "user"}

Шаг 2: Фронтенд генерирует клиент

// Генерируем TypeScript типы и методы
npm run generate:api

// Автоматически появляется src/api/generated/index.ts

Шаг 3: Используем в компоненте

// Полностью типизировано, без any
import { useQuery } from '@tanstack/react-query';
import { usersApi } from '@/api/generated';

function UserProfile({ userId }: { userId: string }) {
  const { data: user, isLoading } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => usersApi.getUser(userId),
  });

  // user.name, user.email точно существуют и типизированы
  if (isLoading) return <Loading />;
  return <div>{user?.name}</div>;
}

Инструменты для работы со Swagger

1. Swagger UI (встроено в FastAPI, Flask, Django)

// Автоматический интерфейс документации
http://localhost:8000/docs

2. ReDoc — альтернатива Swagger UI

// Более красивая документация
http://localhost:8000/redoc

3. Postman

// Импортируем OpenAPI спецификацию
// File -> Import -> URL -> https://api.prepbro.ru/openapi.json
// Все endpoints автоматически добавятся в Postman

4. Insomnia

// Аналог Postman с открытым исходным кодом
// Также поддерживает импорт OpenAPI

Практический пример интеграции

Полный workflow для фронтенд-разработчика:

// 1. Устанавливаем генератор
npm install -D @openapitools/openapi-generator-cli

// 2. Создаем конфиг openapi-generator.yaml
packageName: api
packageVersion: 1.0.0
generatorName: typescript-axios
inputSpec: https://api.prepbro.ru/openapi.json
output: ./src/api/generated

// 3. Добавляем script в package.json
{
  "scripts": {
    "generate:api": "openapi-generator-cli generate"
  }
}

// 4. Генерируем клиент
npm run generate:api

// 5. Используем в коде
import { DefaultApi } from '@/api/generated';

const api = new DefaultApi();
const users = await api.getUsers(); // полностью типизировано!

Альтернатива: TypeScript RPC (tRPC)

Если бэкенд на Node.js/TypeScript, можно использовать tRPC вместо REST + Swagger:

// Бэкенд
const router = t.router({
  users: t.procedure
    .input(z.string().uuid())
    .output(userSchema)
    .query(async ({ input }) => {
      return await db.users.findOne({ id: input });
    }),
});

// Фронтенд — полная type safety БЕЗ кодгена!
const user = await trpc.users.query(userId);
// user точно совпадает с бэкендом

Проблемы и ограничения

1. Swagger specs могут отставать от реальности

Если бэкенд не обновляет спецификацию:

// Swagger говорит: GET /users/{id}
// Но реально бэкенд вернет 400

Решение: Code-first подход (спецификация генерируется из кода).

2. Генерация кода может быть неоптимальной

// Генератор может создать неудобный API
const user = await usersApi.usersRetrieve({ userId: 'id' });
// Вместо
const user = await api.users.get('id');

Решение: Написать свой wrapper или использовать инструмент, который генерирует в стиле вашего проекта.

Лучшие практики

// 1. Версионируйте API
/api/v1/users
/api/v2/users // новая версия

// 2. Документируйте примеры
example: {
  id: "550e8400-e29b-41d4-a716-446655440000",
  name: "John Doe",
  email: "john@example.com"
}

// 3. Используйте enum для статусов
status:
  type: string
  enum: [active, inactive, blocked]

// 4. Подробно описывайте ошибки
404:
  description: Пользователь не найден
  content:
    application/json:
      schema:
        type: object
        properties:
          error: { type: string }
          error_code: { type: string }
          message: { type: string }

Итог

Swagger/OpenAPI для фронтенда:

• Источник истины о API структуре
• Автоматическая генерация типизированных клиентов
• Интерактивная документация и тестирование
• Синхронизация типов бэк- и фронтенда
• Экономия времени на написании API интеграции

Главное преимущество: Code generation обеспечивает type safety и предотвращает баги, связанные с несоответствием фронтенда и бэкенда.