← Все статьи

OpenAPI для сервиса заказов: минимальный контракт с полезными примерами

· 7 мин чтения

Пошаговый разбор создания минимального OpenAPI-контракта для сервиса заказов: структура, схемы данных, ошибки и примеры запросов. Готовый YAML-фрагмент и рекомендации по проверке.

Команда backend-разработчиков завершила написание REST-API для управления заказами, а фронтенд-разработчики ждут точных спецификаций полей для интеграции. Устное описание в чате приводит к несоответствиям: один считает сумму в центах, другой — в рублях; один ожидает массив ошибок, другой — объект. Минимальный, но корректный OpenAPI-контракт устраняет эту неопределённость, предоставляя машиночитаемый источник истины для обоих слоёв.

Цель минимального контракта

Минимальный контракт не означает отсутствие деталей. Он означает фокус на критически важных аспектах взаимодействия: маршруты, методы HTTP, форматы входных и выходных данных, коды состояния и основные ошибки. Избыточная детализация внутренней логики или необязательных параметров создаёт шум и затрудняет поддержку. Контракт отвечает на вопросы: «Какой URL вызвать?», «Какой метод использовать?», «Какие поля обязательны?», «Какой тип данных ожидается?» и «Как обработать ошибку?». Такой подход позволяет быстро сгенерировать клиентский код или мок-сервер, не погружаясь в реализацию. Это особенно важно на ранних этапах проекта, когда параллельно работают несколько команд, и синхронизация через код невозможна.

Базовая структура документа

Документ OpenAPI 3.0 состоит из нескольких ключевых секций. Секция info содержит метаданные о версии и контактах. Секция servers указывает базовые URL. Секция paths описывает эндпоинты. Секция components.schemas определяет переиспользуемые типы данных. Для сервиса заказов достаточно определить две операции: создание заказа и получение списка заказов. Этого хватает для демонстрации основных принципов. Важно отметить, что версия 3.0 использует пространство имён components, тогда как более ранняя версия 2.0 использовала definitions. Смешивание этих структур приводит к ошибкам парсинга, поэтому следует строго придерживаться выбранной версии спецификации.

openapi: 3.0.0
info:
  title: Order Service API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /orders:
    post:
      operationId: createOrder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Заказ создан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: Некорректные данные
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: listOrders
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Список заказов
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderResponse'
components:
  schemas:
    CreateOrderRequest:
      type: object
      required:
        - customer_id
        - items
      properties:
        customer_id:
          type: string
          format: uuid
        items:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - product_id
              - quantity
            properties:
              product_id:
                type: string
                format: uuid
              quantity:
                type: integer
                minimum: 1
    OrderResponse:
      type: object
      required:
        - id
        - status
        - total_amount_cents
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - paid
            - shipped
            - cancelled
        total_amount_cents:
          type: integer
          description: Сумма в центах
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string

Проектирование схем данных

В учебном контракте валюта зафиксирована как USD: total_amount_cents хранит целое число центов. Если сервис поддерживает несколько валют, к сумме добавляют обязательное поле currency и согласуют правила пересчёта. В таком контракте название cents уже не универсально для всех валют.

Выбор типов данных напрямую влияет на надёжность интеграции. Для финансовых величин используется целочисленный тип integer с суффиксом _cents, чтобы избежать проблем с округлением десятичных дробей, характерных для типа float. Идентификаторы оформляются как строки формата UUID, что позволяет использовать распределённую генерацию при выбранном способе и контроле уникальности. Поле items в запросе создания заказа является массивом объектов. Каждый элемент массива требует указания product_id и quantity. Использование minItems: 1 предотвращает создание пустого заказа, что имеет смысл на уровне контракта, даже если бизнес-логика допускает иные сценарии. В ответе OrderResponse поле status ограничено перечислением значений, что позволяет клиентскому коду компилировать обработку состояний статически. Это снижает риск ошибок времени выполнения, связанные с неожиданными строковыми значениями статуса.

Описание операций и параметров

Операция createOrder использует метод POST. Она принимает тело запроса, соответствующее схеме CreateOrderRequest. Успешный ответ возвращается с кодом 201 Created и телом OrderResponse. Код 400 Bad Request возвращает объект ошибки. Операция listOrders использует метод GET. Параметр limit передаётся в строке запроса и ограничен диапазоном от 1 до 100. Это ограничение защищает сервер от чрезмерной нагрузки и помогает клиенту планировать пагинацию. Отсутствие параметра offset или курсора в этом минимальном примере упрощает контракт, но в реальной системе потребуется механизм навигации по большим спискам. Важно, что параметры запроса описаны явно, а не подразумеваются. Явное описание позволяет инструментам автоматической проверки (linters) выявлять несоответствия между документацией и фактическим кодом.

Обработка ошибок

Единая схема ошибки Error содержит два поля: code и message. Поле code — машинночитаемый идентификатор ошибки, например INVALID_QUANTITY или CUSTOMER_NOT_FOUND. Поле message — человекочитаемое описание. Такая структура позволяет клиентским приложениям автоматически обрабатывать известные коды ошибок, показывая пользователю понятное сообщение. Альтернативный подход — использование отдельных схем для каждого типа ошибки — усложняет контракт без существенной пользы для минимальной версии. Код 404 Not Found может быть добавлен позже, если потребуется поддержка получения отдельного заказа по ID. Сейчас контракт намеренно ограничен двумя операциями. Стандартизация формата ошибок критична, так как разные фреймворки по-разному сериализуют исключения. Явная схема гарантирует предсказуемость поведения API независимо от внутренней реализации.

Проверка контракта

После написания YAML-файла необходимо выполнить проверку валидности. Инструменты вроде Swagger Editor или онлайн-валидаторы OpenAPI проверяют соответствие структуре спецификации 3.0. Типичные ошибки на этапе валидации: неправильный синтаксис YAML (отступы, двоеточия), ссылки на несуществующие схемы ($ref), отсутствие обязательных свойств в ответах. После успешной валидации рекомендуется сгенерировать интерактивную документацию (Swagger UI). Это визуальная проверка: можно отправить тестовый запрос через интерфейс и увидеть, как система реагирует. Хотя это учебный пример, процесс генерации UI выявляет логические несоответствия, которые не видны в сыром тексте. Регулярная валидация в CI-пайплайне предотвращает попадание битых контрактов в production.

Частые ошибки при создании

Ниже приведены типичные проблемы, встречающиеся при разработке подобных контрактов:

ОшибкаПоследствиеКак исправить
Использование float для денегПотери точности при суммированииИспользовать integer в минимальных единицах (центы)
Отсутствие required в схемахКлиент может отправить неполные данныеЯвно указать обязательные поля в списке required
Размытые описания полейРазное понимание смыслов разными разработчикамиДобавить атрибут description к каждому полю
Неограниченный размер массивовУязвимость к DoS-атакамУказать maxItems для массивов
Отсутствие кодов ошибокКлиент не может различать типы сбоевОписать схему Error и коды ответов 4xx/5xx

Интеграция в рабочий процесс

Контракт OpenAPI следует хранить в репозитории вместе с кодом. Файл openapi.yaml проходит те же процедуры ревью, что и исходный код. Изменения в контракте должны сопровождаться обновлением версии в секции info.version. Если изменения обратно несовместимы (удаление полей, изменение типов), требуется увеличение мажорной версии. Для совместимых изменений (добавление необязательных полей) достаточно увеличения минорной версии. Автоматизация процесса возможна через CI/CD-пайплайны: каждый пул-реквест запускает валидатор OpenAPI и генерирует diff-отчёт изменений. Это помогает отслеживать эволюцию интерфейса и предупреждает о случайных поломках контракта. Такой подход превращает API в управляемый актив, а не во временный артефакт разработки.

Пределы минимализма

Минимальный контракт не заменяет полную документацию. Он не описывает аутентификацию, лимиты запросов, детали пагинации, webhook'и или асинхронные процессы. Однако он устанавливает фундаментальный уровень договорённости. Расширение контракта должно происходить постепенно: сначала добавить аутентификацию (security schemes), затем пагинацию (cursor-based), затем события. Каждое расширение требует обновления версии и уведомления клиентов. Попытка создать «идеальный» контракт с первого раза часто приводит к тому, что документ становится громоздким и трудно поддерживаемым. Лучше начать с ядра, убедиться, что оно работает, и добавлять детали по мере необходимости. Инкрементальный подход снижает риск технических долгов и облегчает миграцию клиентов.

Практическое применение

Откройте редактор OpenAPI, вставьте YAML и проверьте структуру контракта в предпросмотре документации. Отдельно сопоставьте обязательные поля, примеры и ответы с бизнес-правилами. Успешный разбор файла не доказывает, что сервис реализует эти правила; для этого нужны тесты реализации. Для углубленного изучения принципов contract-first разработки см. статью «Contract-first API».