Документирование допустимых значений фильтра в OpenAPI — это способ гарантировать корректную работу API на стороне клиента. Четкое описание ограничений предотвращает ошибки при запросах, снижает нагрузку на сервер и упрощает разработку интеграций. Правильная спецификация позволяет инструментам разработки (например, Swagger UI) генерировать валидные примеры данных автоматически.

Как документировать допустимые значения фильтра в OpenAPI: пошаговая инструкция

Начните с определения компонента схемы (schema), который будет использоваться для параметров запроса. В объекте parameters укажите тип параметра как query, path или header в зависимости от места передачи фильтра.

Используйте поле schema внутри объекта параметра для описания структуры данных фильтра. Это позволяет использовать все возможности OpenAPI для валидации.

Определите допустимые значения через ключевые слова JSON Schema: enum для перечисления, minimum/maximum для диапазонов, pattern для строк и multipleOf для кратных значений.

Добавьте описание (description) на русском языке или языке интерфейса, чтобы разработчики понимали назначение фильтра без чтения кода.

Проверьте документацию в Swagger UI или ReDoc. Убедитесь, что выпадающие списки и поля ввода отображаются корректно с учетом заданных ограничений.

Типы значений для параметров фильтрации (enum, range, pattern)

Для дискретных наборов значений используйте ключевое слово enum. Оно принимает массив строк или чисел. Например, фильтр по статусу заказа может принимать значения 'active', 'pending', 'closed'.

Для числовых диапазонов применяйте minimum и maximum. Если нужно указать шаг, добавьте multipleOf. Это полезно для фильтрации по датам (например, с шагом в месяц) или количественным показателям.

Для текстовых фильтров используйте pattern с регулярными выражениями. Например, фильтр по коду страны может принимать только двухзначные числа: ^[0-9]{2}$.

Сочетание нескольких ограничений возможно. Можно задать enum для типа валюты и minimum/maximum для суммы в этой валюте в одном объекте схемы.

Спецификация формата данных (format) и примеры использования

Поле format указывает стандартный формат данных. Для дат используйте date-time или date, для чисел — int64 или double. Это помогает клиентам корректно парсить данные.

Пример: параметр фильтра по дате создания заказа с форматом date-time и ограничением maximum на текущую дату предотвращает запросы в будущее.

Для email-фильтров используйте format email, хотя для строк чаще достаточно type string. Спецификация формата помогает инструментам генерации валидных тестовых данных.

Описание полей с несколькими возможными значениями (multipleOf, maxItems)

Ключевое слово multipleOf ограничивает значения кратными определенному числу. Например, фильтр по количеству товаров должен быть кратен 1 или 5.

Для массивов используйте maxItems и minItems. Если фильтр возвращает список категорий, укажите максимальное количество элементов в ответе.

Важно различать ограничения на входные данные фильтра и ограничения на выходные данные. Для входных параметров используйте multipleOf, для выходных — maxItems.

Обработка ошибок при некорректных значениях фильтра

Если клиент передает значение вне допустимого диапазона или не из enum, сервер должен вернуть ошибку 400 Bad Request.

В теле ответа укажите поле detail с понятным сообщением на языке клиента. Например: 'Значение статуса должно быть одним из: active, pending'.

Используйте компонент responses в схеме операции для описания ошибок. Это позволяет клиентам заранее знать структуру ошибки и обрабатывать её корректно.

Не возвращайте пустой ответ или ошибку 500 при некорректном фильтре. Всегда сообщайте причину отказа.

Примеры реализации в Swagger/OpenAPI 3.0/3.1

В OpenAPI 3.0 и 3.1 структура описания фильтра практически идентична. Разница лишь в синтаксисе компонентов.

Пример для фильтра по статусу заказа:

В примере показан параметр status с типом string и перечислением допустимых значений через enum. Описание на русском языке помогает разработчикам понять назначение поля.

Пример для числового диапазона:

Здесь использованы minimum и maximum для ограничения суммы заказа. multipleOf=10 означает, что сумма должна быть кратна 10.

Пример с регулярным выражением:

Фильтр по коду страны принимает только двухзначные числа. Pattern обеспечивает валидацию на стороне клиента до отправки запроса.

Частые ошибки при описании фильтров и способы их избежать

Ошибка: отсутствие enum для дискретных значений. Решение: всегда перечисляйте все возможные варианты, если их数量有限.

Ошибка: использование pattern без объяснения. Решение: добавляйте description с примером или ссылкой на документацию по формату кода.

Ошибка: игнорирование формата даты. Решение: укажите date-time для ISO 8601, чтобы клиенты не пытались парсить строку как число.

Ошибка: слишком широкие диапазоны. Решение: сужайте minimum и maximum до реальных бизнес-ограничений, чтобы избежать лишних запросов.

Интеграция документации фильтра с бизнес-логикой

Связывайте технические ограничения с бизнес-правилами. Например, если система не поддерживает заказы старше 3 лет, укажите maximum для даты создания.

Используйте description для объяснения причин ограничений. Клиент должен понимать, почему нельзя передать значение 1000000, если лимит — 100000.

Документируйте зависимости между фильтрами. Если фильтр по статусу 'closed' несовместим с фильтром по дате отгрузки, укажите это в description или через x-extensions.

Регулярно обновляйте документацию при изменении бизнес-логики. Устаревшие ограничения ведут к ошибкам на стороне клиентов.

Вопросы и ответы

Можно ли использовать enum для числовых значений?

Да, в OpenAPI тип enum может содержать как строки, так и числа. Это позволяет задать точный набор допустимых чисел без использования диапазонов.

Как описать фильтр с несколькими уровнями иерархии?

Используйте вложенные схемы или составной тип object. Для каждого уровня укажите свои ограничения через minimum, maximum или enum.

Нужно ли указывать format для всех типов данных?

Нет, format обязателен только для специфических типов (date-time, email и т.д.). Для простых строк и чисел формат не требуется, если не используется стандартный.

По теме

parameters:
  - name: status
    in: query
    required: false
    schema:
      type: string
      enum:
        - active
        - pending
        - closed
      description: Статус заказа (только эти значения допустимы)
parameters:
  - name: min_amount
    in: query
    required: false
    schema:
      type: integer
      minimum: 100
      maximum: 10000
      multipleOf: 10
      description: Сумма заказа должна быть от 100 до 10000 и кратна 10

Похожие статьи