Документация API и где это пригодится в работе

Документация API

Как узнать, какие эндпоинты есть у API, какие параметры они принимают и что вернут? Из документации. В ней для каждого эндпоинта описаны:

• метод и путь: GET /products/{id};
• параметры: какие обязательные, какого типа;
• тело запроса: какие поля и в каком формате;
• ответы: пример тела для успешного ответа и для каждой ошибки с её кодом;
• авторизация: нужен ли токен.

Фигурные скобки в пути /products/{id} — обозначение места для значения: вместо {id} подставляют номер товара.

Swagger и OpenAPI

Большинство API описывают в стандартном формате OpenAPI — это файл YAML или JSON со всеми эндпоинтами. По нему автоматически строится страница документации Swagger UI:

• эндпоинты сгруппированы по разделам, у каждого — описание, параметры и примеры;
• кнопка Try it out позволяет отправить запрос прямо со страницы документации;
• раздел Schemas описывает модели данных: какие поля у товара, у заказа, у пользователя.

Найти Swagger у своего проекта обычно просто: спросите разработчиков или попробуйте адреса вида /swagger или /docs на тестовом сервере.

Файл OpenAPI можно импортировать в Postman: кнопка Import → выбрать файл или вставить ссылку. Postman создаст коллекцию со всеми эндпоинтами — останется только добавить окружение и тесты.

Документация — главный источник правды для тестировщика. Если API ведёт себя не так, как написано, ошибка либо в API, либо в документации, и про оба случая нужно сообщить.

Баг-репорт по API

Хороший баг-репорт позволяет разработчику повторить ошибку за минуту:

• название: «Поиск товаров возвращает 500 при пустом параметре q»;
• окружение: тестовый сервер, дата;
• запрос: метод, адрес, параметры и тело. Удобнее всего приложить команду curl из кнопки Code в Postman;
• ожидаемый результат: «код 400 и сообщение о пустом запросе» — со ссылкой на документацию;
• фактический результат: код и тело ответа.

Токены, пароли и персональные данные в баг-репорт не попадают: их заменяют на <token> и <password>. Подробно о баг-репортах — в курсе «Тестировщик с нуля».

Где это пригодится

• Тестировщику — тестирование API есть почти в каждой вакансии: проверка эндпоинтов, негативные сценарии, коллекции с автотестами. Посмотрите курс «Тестировщик с нуля».
• Аналитику — системные аналитики описывают API в требованиях: какие поля, какие ошибки, как связаны системы. А потом проверяют интеграцию в Postman. О работе аналитика — в курсе «1С-аналитик».
• Бэкенд-разработчику — проверить свой API, не дожидаясь интерфейса. Как написать простой сервер, показано в курсе «Основы Golang».
• Мобильному и фронтенд-разработчику — понять, что вернёт сервер, и проверить запросы до того, как писать код. Подробнее — в курсе «Android-разработчик».

GET {{baseUrl}}/carts/user/33

const json = pm.response.json();

pm.test("Код ответа 200", function () {
  pm.response.to.have.status(200);
});

pm.test("Все корзины принадлежат пользователю 33", function () {
  json.carts.forEach(function (cart) {
    pm.expect(cart.userId).to.eql(33);
  });
});