В прошлом уроке мы собрали коллекцию запросов в Postman — но для этого нужно было знать, какие эндпоинты вообще есть у API. Что делать, если интерфейс продукта ещё не готов, а API уже разработан? Разбираемся, как тестировщик может начать проверять API напрямую по документации, не дожидаясь ни одной готовой кнопки.
Чему научишься за этот урок:
— понимать, что такое Swagger и OpenAPI и как читать спецификацию;
— пользоваться Swagger UI для изучения эндпоинтов;
— составлять проверки по документации ещё до появления интерфейса.
Swagger и OpenAPI: стандарт описания API
Swagger / OpenAPI — стандарт описания REST API. Это документ (обычно в формате YAML или JSON), где для каждого эндпоинта прописано: HTTP-метод, параметры запроса, формат ответа, возможные коды ответа. По сути, это точная техническая инструкция, как API должен работать, ещё до того, как кто-то написал хоть строчку интерфейса.
Читать такой документ построчно в YAML неудобно, поэтому есть Swagger UI — интерактивная веб-страница, которая рендерит спецификацию в удобочитаемый вид: список эндпоинтов, а для каждого можно раскрыть параметры и даже отправить тестовый запрос прямо со страницы документации, без Postman.
Коды ответа, которые вы увидите в Swagger UI напротив каждого эндпоинта — это те же самые коды 200/400/401/404/500, которые вы уже разбирали в главе 3. Никакой новой системы кодов учить не нужно — меняется только то, откуда вы их узнаёте: не из вкладки Network после клика, а из документации заранее.
Раннее подключение: тестируем API до готового интерфейса
Ключевая ситуация этого урока: интерфейс (UI) продукта ещё НЕ готов, а API уже разработан и задокументирован через Swagger. В таком случае тестировщику не нужно ждать, пока разработчики фронтенда нарисуют кнопки, — он может начать тестировать API напрямую по документации. Это то же раннее подключение к тестированию, тот же принцип «сдвиг влево», который вы разбирали на V-модели в уроке 2.1 — только теперь применительно не ко всему проекту, а конкретно к API.
По спецификации составляют проверки для каждого эндпоинта: какие параметры обязательны, какой формат ответа ожидается (какие поля, какого типа), какие коды ответа возможны в разных ситуациях.
Пример: эндпоинт записи на курс
Допустим, в Swagger описан эндпоинт записи пользователя на курс:
POST /api/courses/{id}/enroll
Параметры:
id -> номер курса (в пути)
user_id -> номер пользователя (обязательный)
Ответы:
201 -> запись прошла успешно
404 -> курса с таким id не существует
Кнопки «Записаться» в интерфейсе продукта ещё нет — фронтенд её не нарисовал. Но тестировщик уже может составить и выполнить проверки прямо по этой спецификации: отправить запрос с корректным user_id на существующий курс и убедиться, что приходит 201; отправить запрос на несуществующий id курса и убедиться, что приходит 404; попробовать отправить запрос без обязательного параметра user_id и посмотреть, что вернёт сервер. Всё это — ещё до того, как в интерфейсе появится хоть один пиксель формы записи.
Итог:
— Swagger / OpenAPI — стандарт описания REST API: метод, параметры, формат ответа, коды ответа для каждого эндпоинта;
— Swagger UI рендерит спецификацию в удобочитаемый вид и позволяет отправлять тестовые запросы прямо со страницы;
— если интерфейс продукта ещё не готов, а API уже задокументирован, тестировщик может начать проверки API напрямую по спецификации — раннее подключение, тот же принцип «сдвиг влево»;
— проверки составляют по обязательным параметрам, формату ответа и возможным кодам ответа для каждого эндпоинта.
Контрольный вопрос. Что такое Swagger / OpenAPI?
Подсказка: В начале урока прямо дано определение — это документ, описывающий, а не выполняющий запросы.
Проверить ответ →
Реальная проверка — на нашей платформе, бесплатно и без регистрации. Открыть задачу и ввести ответ →
Контрольный вопрос. Что делает Swagger UI?
Подсказка: В уроке описано, во что превращается спецификация, когда её открывают через эту страницу.
Проверить ответ →
Реальная проверка — на нашей платформе, бесплатно и без регистрации. Открыть задачу и ввести ответ →
Контрольный вопрос. В ключевой ситуации этого урока интерфейс продукта ещё не готов. Что при этом может сделать тестировщик?
Подсказка: В уроке прямо названо это «раннее подключение» — вспомни, к чему оно относится.
Проверить ответ →
Реальная проверка — на нашей платформе, бесплатно и без регистрации. Открыть задачу и ввести ответ →
Контрольный вопрос. Тестирование API по документации до готового интерфейса — это применение какого принципа, уже знакомого из урока 2.1?
Подсказка: В уроке прямо названа связь с V-моделью и её ключевым принципом из главы 2.
Проверить ответ →
Реальная проверка — на нашей платформе, бесплатно и без регистрации. Открыть задачу и ввести ответ →
Контрольный вопрос. В Swagger описан эндпоинт POST /api/courses/{id}/enroll с обязательным параметром user_id и кодами ответа 201 (успех) и 404 (курс не найден). Какие проверки тестировщик может составить по этой спецификации ещё до готового интерфейса (выбери все подходящие)?
Выберите все верные варианты.
Подсказка: Сверь варианты с примером из урока про эндпоинт enroll — один из них противоречит идее раннего подключения.
Проверить ответ →
Реальная проверка — на нашей платформе, бесплатно и без регистрации. Открыть задачу и ввести ответ →
Контрольный вопрос. Как называется интерактивная веб-страница, которая рендерит спецификацию Swagger в удобочитаемый вид и позволяет отправлять тестовые запросы прямо с неё? Ответь двумя словами.
Подсказка: Название совпадает с названием стандарта плюс ещё одно короткое слово из трёх букв.
Проверить ответ →
Реальная проверка — на нашей платформе, бесплатно и без регистрации. Открыть задачу и ввести ответ →
Задание. В Swagger описан эндпоинт /api/courses/{id}/enroll, который создаёт новую запись ученика на курс и в ответ возвращает 201. Какой HTTP-метод из уже изученных в этом курсе обычно используют для создания новой сущности, а не для её чтения или удаления? Ответь одним словом.
Подсказка: Вспомни, какой из методов HTTP обычно используют, когда создают что-то новое.
✅ Готово, если: ты ввёл(а) верный ответ, и онлайн-проверка его приняла.
Проверить ответ →
Реальная проверка — на нашей платформе, бесплатно и без регистрации. Открыть задачу и ввести ответ →
Задание. По спецификации из урока эндпоинт POST /api/courses/{id}/enroll возвращает 201 при успешной записи. Также в Swagger описан отдельный код ответа для случая, когда курса с таким id не существует. Какой это код? Ответь числом.
Подсказка: Посмотри на таблицу «Ответы» из ASCII-схемы урока и найди строку про несуществующий курс.
✅ Готово, если: ты ввёл(а) верный ответ, и онлайн-проверка его приняла.
Проверить ответ →
Реальная проверка — на нашей платформе, бесплатно и без регистрации. Открыть задачу и ввести ответ →
Задание. Объясни в 2-3 предложениях: почему тестировщику полезно уметь тестировать API по документации Swagger, даже если интерфейс продукта уже готов?
Критерий приёмки: объяснено, что документация даёт точный список обязательных параметров, форматов ответа и возможных кодов ответа для каждого эндпоинта, поэтому по ней можно составить полные и однозначные проверки, а не гадать, что попробовать, кликая по готовому интерфейсу.
Подсказка: Вспомни, что именно даёт спецификация тестировщику: список параметров, формат ответа, коды — и как это помогает составлять проверки.
✅ Готово, если: программа запускается без ошибок и выводит то, что просят в задании.
Онлайн-проверка ответа появится позже
Задание. Команда разрабатывает новый раздел «Запись на курс». Бэкенд-разработчики уже выложили эндпоинт POST /api/courses/{id}/enroll и его Swagger-спецификацию с обязательным параметром user_id и кодами 201/404. Фронтенд-команда говорит, что кнопка «Записаться» будет готова только через 2 недели. Опиши в 2-3 предложениях, что может сделать тестировщик прямо сейчас, не дожидаясь этих двух недель, и почему это выгоднее, чем просто ждать.
Критерий приёмки: описано, что тестировщик может уже сейчас составить и выполнить проверки эндпоинта напрямую по спецификации (успешная запись — 201, несуществующий курс — 404, запрос без обязательного user_id), не дожидаясь готового интерфейса. Это выгоднее ожидания, потому что баги на стороне API находят и чинят раньше — до того, как на них наслоится ещё и фронтенд (принцип раннего подключения / «сдвиг влево»).
Подсказка: Вспомни ключевую ситуацию урока: что можно проверить, если API уже задокументирован, а интерфейса ещё нет — и почему раньше значит дешевле.
✅ Готово, если: программа запускается без ошибок и выводит то, что просят в задании.
Онлайн-проверка ответа появится позже
Что дальше
Теперь вы умеете составлять проверки по документации API. Но одного факта «код ответа правильный» недостаточно — в следующем уроке разберём, по каким осям вообще проверяют ответ API, чтобы не упустить дефект.
