Главная Мануалы REST API с нуля — курс для новичка Инструменты на каждый день — Postman, Swagger, моки

Инструменты на каждый день — Postman, Swagger, моки

Знать REST мало — нужно уметь с ним удобно работать. Три инструмента, без которых редко обходится боевая разработка API.

Postman / Insomnia — швейцарский нож запросов

Десктопные приложения для отправки запросов руками. В DevTools тоже можно вставить fetch в консоль, но Postman даёт несравнимо больше:

Удобные формы для URL, метода, заголовков, тела — не нужно держать в голове JS-синтаксис.
Коллекции запросов — сохраняете типичные сценарии, делите с командой.
Переменные окружения — один и тот же набор запросов прогоняется на dev, staging, prod без правок.
Цепочки запросов — результат одного автоматически кладётся в переменную для следующего (например, токен из /login используется в /me).
Автотесты на ответ — пишутся прямо в Postman, проверяют статус, схему JSON, отдельные поля.
История запросов — можно вернуться к тому, что отправляли вчера.

Интерфейс Postman при отладке REST-запроса

Insomnia — альтернатива с похожим набором функций, проще и легче.

На каждом проекте, где есть собственный API, рано или поздно появляется «команда коллекций Postman», в которую складывают все типичные запросы. Это и документация, и тестовый стенд, и упражнение для нового разработчика — «разберись, прогони».

Swagger / OpenAPI — документация и спецификация

OpenAPI — это стандарт описания REST API в виде YAML или JSON-файла. Swagger — набор инструментов вокруг OpenAPI: рендерер документации (Swagger UI), кодогенератор клиентов, валидатор.

Типичный кусок OpenAPI:

paths:
  /api/posts/{id}:
    get:
      summary: Получить пост по id
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '404':
          description: Не найден

components:
  schemas:
    Post:
      type: object
      properties:
        id: { type: integer }
        title: { type: string }
        body: { type: string }

На основе такого файла Swagger UI рисует интерактивную документацию: список endpoint, параметры, примеры запросов и ответов, кнопка «Try it out» — можно прямо в браузере отправить запрос. Многие API публикуют такую документацию открыто (GitHub, Stripe, OpenWeather).

Кодогенераторы умеют по тому же файлу сгенерить готовый TypeScript-клиент со всеми типами и методами — экономия часов работы и страховка от опечаток в URL.

Окно Swagger UI на примере petstore — структура API и кнопка теста

Моки — когда бэка ещё нет

Частая ситуация: фронт и бэк делают параллельно. Бэка ещё нет, спецификация согласована, экран нужно собрать сейчас. Чтобы не ждать — делают мок: фейковый сервер, который отвечает заранее придуманными данными.

Три популярных подхода.

1. Mock Service Worker (MSW)

Библиотека, которая перехватывает fetch-запросы внутри браузера и возвращает заданные ответы. Сетевого запроса фактически нет — всё работает локально. Лучше всего подходит для разработки и тестов.

// Описываем хендлер:
http.get('/api/posts', () => {
  return HttpResponse.json([{ id: 1, title: 'Mock' }]);
});

2. JSON Server

Готовый локальный сервер, который из обычного JSON-файла поднимает полный REST API: GET, POST, PUT, PATCH, DELETE, пагинация, фильтры. Хорош, когда нужно «поднять бэк за минуту».

// db.json — наш файл:
{ "posts": [{ "id": 1, "title": "Hello" }] }

// Поднимаем:
npx json-server db.json
// → http://localhost:3000/posts

3. Mock в Postman

Postman умеет поднимать публичный URL, который возвращает заранее заданные ответы. Удобно, когда нужен мок не только для себя, но и для тестов или для других команд.

Что освоить сразу

На первой работе джуну хватит:

Поставить Postman или Insomnia. Уметь отправить GET/POST с телом, поставить заголовок Authorization, прочитать ответ.
Уметь читать Swagger UI — чтобы по документации команды собирать запросы, не дёргая бэкенд по каждому полю.
Знать, что моки существуют, и видеть, когда они уместны (а не «писать в код фейковые данные», что часто делают начинающие).

GraphQL, gRPC, WebSocket, OpenAPI-кодогенерация — всё это можно дойти и осваивать постепенно, по мере появления задач. REST — обязательный минимум, и его уже знаете.

Итог мануала

Здесь заканчивается содержательная часть курса. Если читали внимательно — за десять модулей сложилась цельная картина: устройство HTTP, REST как стиль, fetch на практике, тонкости передачи данных, обработка ошибок, авторизация, CORS, мини-проект, обзор альтернатив.

Осталось одно — финальный тест на усвоение материала. Проверьте себя в следующем разделе.

Предыдущая Следующая