Softonic

Проверка обязательных полей OpenAPI

Шаг 1 / 2
Далее

Прежде чем передать описание API коллеге, клиенту или генератору документации, убедитесь, что обязательные поля на месте. Вставьте документ выше, и инструмент подтвердит поле версии, info.title, info.version и paths, а также перечислит всё, чего не хватает.

Как проверить обязательные поля

  1. 1

    Вставьте документ

    Вставьте спецификацию в формате JSON или YAML, даже если она ещё в работе.

  2. 2

    Запустите проверку

    Перейдите к шагу результатов. Каждое отсутствующее поле выводится отдельной ошибкой.

  3. 3

    Добавьте недостающее

    Добавьте перечисленные поля в свой файл, используя фрагменты ниже.

  4. 4

    Проверьте снова

    Вставьте обновлённую спецификацию и запустите проверку, пока ошибки не исчезнут.

Четыре обязательных элемента

Поле Где находится Пример
Поле версии Верхний уровень openapi: 3.0.3 или swagger: "2.0"
info.title Внутри info title: Orders API
info.version Внутри info version: 1.0.0
paths Верхний уровень paths: хотя бы с первым маршрутом

Значение info.version, это версия вашего собственного API, а не версия спецификации OpenAPI. Его часто пропускают, потому что версия спецификации уже указана вверху.

Пример, в котором всё отсутствует

servers:
  - url: https://api.example.com

В этом крошечном документе нет ни одного обязательного элемента. Отчёт перечисляет три ошибки:

Результат Тип
Missing ‘openapi’ or ‘swagger’ version field. Ошибка
Missing ‘info’ object. Ошибка
Missing ‘paths’ object. Ошибка

Когда весь объект info отсутствует, инструмент сообщает только об этой ошибке и не перечисляет title и version отдельно. Добавьте info с обоими полями, и при следующем запуске будет видно, если что-то ещё не заполнено.

Стартовый каркас

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders

Этот каркас проходит все проверки обязательных полей. Замените названия на свои и расширяйте его дальше. Ответы, схемы и безопасность в эту проверку не входят.

Когда запускать проверку

Запускайте её, когда начинаете спецификацию с нуля, после генерации её из кода и перед отправкой тому, кто импортирует её в другой инструмент. Многие импортёры останавливаются на первом отсутствующем обязательном поле с коротким сообщением, поэтому выявление всех полей за один проход экономит несколько итераций. Это также напоминание для новичков, которые часто забывают info.version или пропускают paths, набрасывая API.

Когда обязательные поля проходят проверку, полезно добавить короткое description в info, запись в servers и operationId для каждой операции. Этих элементов здесь не проверяют, но они делают спецификацию понятнее и облегчают генерацию клиентского кода.

Часто задаваемые вопросы

Нет. Поле openapi указывает, какую версию спецификации вы используете. info.version, это версия вашего собственного API, например 1.0.0.

Ключ должен существовать как объект, и эта проверка не требует маршрутов внутри него. Добавьте реальные маршруты перед публикацией.

Проверки title и version выполняются, только если объект info существует. Добавьте его и запустите проверку снова, чтобы увидеть, полностью ли заполнены его поля.

Нет. Здесь обязательны только поле версии, info, title, version и paths. Детали на уровне операций не проверяются.

Сопутствующие инструменты

Генератор вымышленных телефонных номеров

Создавайте до 50 вымышленных номеров из официально зарезервированных диапазонов пяти стран.

Генератор конфигурации webpack

Создайте webpack.config.js для webpack 5 под чистый JavaScript, React или Vue: TypeScript, Babel, CSS или Sass, изображения, HtmlWebpackPlugin, dev-сервер и команда npm install.

Генератор случайных букв

Генерируйте случайные буквы A-Z. Выберите количество, верхний или нижний регистр либо смешанный вариант для игр, заданий и уроков.

Валидатор XSD

Проверьте XML-документ в соответствии с схемой XSD и выявите несоответствия между элементами и их типами, указав точные номера строк.

Генератор случайных адресов

Создавайте 1–20 похожих на адрес записей для макетов и тестов в трёх упрощённых форматах.

Конвертер размера файлов

Преобразуйте значения между байтами, КБ, МБ, ГБ, ТБ и двоичными единицами IEC (KiB, MiB, GiB, TiB), свободно сочетая десятичные и двоичные единицы.

Инструмент доступен на других языках

Руководства и сценарии использования