Swagger

Swagger

Что такое Swagger

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

Swagger-документация описывает:

• Все эндпоинты (пути, методы)
• Параметры запроса (в URL, в заголовках, в теле)
• Структуру тел запроса и ответа
• Коды ответов и их схемы
• Требования к авторизации

Swagger UI

Swagger UI — это интерактивный веб-интерфейс, который читает OpenAPI-описание и отображает его как удобную документацию. Главная особенность: прямо в браузере ты можешь отправить реальный запрос и увидеть ответ.

Где его найти: обычно по одному из путей:

• /swagger
• /api-docs
• /docs
• /swagger-ui.html

Как читать Swagger

Описание эндпоинта

POST /api/users
Summary: Create a new user

Параметры запроса (Request Body):

{
  "name": string  (required)
  "email": string (required, format: email)
  "age":   integer (optional, minimum: 18)
}

Возможные ответы:

201 Created     — пользователь создан, тело: { id, name, email }
400 Bad Request — ошибка валидации, тело: { error, details }
409 Conflict    — email уже занят

Как использовать Swagger UI для тестирования

1. Открываешь Swagger UI в браузере
2. Находишь нужный эндпоинт
3. Нажимаешь "Try it out"
4. Заполняешь поля (параметры, тело запроса)
5. Нажимаешь "Execute"
6. Видишь реальный ответ: статус-код, заголовки, тело

Это удобно для первичного изучения API — быстрее, чем настраивать Postman с нуля.

Swagger как источник истины

Swagger UI — это официальная спецификация API. Именно отсюда берёшь:

• Точные имена полей (регистр имеет значение: userId ≠ user_id)
• Обязательность полей
• Типы данных и ограничения (минимальная длина, формат)
• Все возможные коды ответов

Ограничения Swagger

Swagger не всегда отражает реальность:

Расхождение между Swagger и реальным поведением API — это баг в документации. Его тоже нужно фиксировать.

OpenAPI-спецификация

Под Swagger UI лежит файл — swagger.json или openapi.yaml. Это машинно-читаемое описание API.

openapi: 3.0.0
paths:
  /api/users:
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created

Этот файл можно импортировать в Postman и автоматически создать коллекцию со всеми запросами.

Импорт Swagger в Postman

1. В Postman: Import → Link → вставить URL swagger.json (https://api.example.com/api-docs)
2. Postman создаёт коллекцию со всеми эндпоинтами
3. Настраиваешь переменные, добавляешь тесты — и готово

Что мы запомним

• Swagger / OpenAPI — стандарт описания REST API, машинно-читаемая документация
• Swagger UI позволяет отправлять реальные запросы прямо из браузера ("Try it out")
• Обычно находится по путям /swagger, /api-docs, /docs
• Используй Swagger как источник истины: точные имена полей, типы, обязательность, коды ответов
• Расхождение Swagger с реальным поведением — это баг в документации, его тоже нужно фиксировать
• OpenAPI-файл (swagger.json) можно импортировать в Postman