OpenAPI: читаем и пишем контракт метода

OpenAPI — машиночитаемый контракт REST-API в YAML или JSON. Из одного файла получают документацию, заглушки (моки), проверку запросов и клиентский код. Курс пишет по версии 3.1: её схемы — это JSON Schema 2020-12 из прошлого урока. Версия 3.2 (сентябрь 2025) совместима с 3.1 и добавляет новое — достаточно знать, что она есть. Подход contract-first (API first): сначала контракт, его согласуют фронтенд и бэкенд, потом код — и команды работают параллельно. Верхний уровень документа: • openapi — версия спецификации, например 3.1.0; • info — название, описание и версия самого API; • servers — базовые адреса: https://api.romashka.example/v1; • paths — пути ресурсов и их методы; • components — общие схемы (schemas), ответы (responses) и схемы доступа (securitySchemes). На них ссылаются через $ref, а не переписывают в каждом методе. Метод описан внутри своего пути, уровень за уровнем, — шаги ниже. Параметр задают полями name, in (path, query, header или cookie), required и schema. Параметр пути всегда required: true. Чек-лист метода для аналитика: • назначение — summary и operationId; • параметры с типами и обязательностью; • тело запроса (requestBody) со схемой и примером; • все ответы — и успешные, и ошибочные, а не только 200; • формат ошибки; • требования доступа (security).