Таблица полей API (Markdown, Confluence, HTML)

Описание полей по примеру JSON или JSON Schema: таблица с типами, обязательностью, ограничениями и примерами для документации.

Данные обрабатываются в браузере и никуда не отправляются

Источник

Формат

Заголовки

Ввод

Перетащите файл сюда или выберите на диске

Результат

Здесь появится результат

Введите данные слева - результат появится сразу

Как пользоваться

Вставьте пример JSON или схему JSON Schema (определяется автоматически) - таблица полей появляется сразу. Для каждого поля показывается путь (вложенные поля - через точку, элементы массива - через []), тип, обязательность, описание, ограничения и пример. Таблицу можно скопировать в Markdown, разметку Confluence, HTML или CSV и вставить в документацию или требования.

По схеме таблица получается точной: описания (description), перечисления, форматы и ограничения берутся из неё, ссылки $ref и allOf раскрываются. По примеру данных получается заготовка: колонку «Описание» нужно заполнить вручную, а «Обязательное» означает, что поле есть во всех объектах примера.

Частые ошибки

Вот что стоит учесть, документируя поля по JSON:

Пример не знает обязательности

По одному объекту нельзя понять, какие поля обязательные. Вставьте несколько записей, в том числе с пропусками, либо используйте схему - в ней обязательность задана явно.

Описания придётся писать самим

Из примера нельзя узнать смысл поля. Таблица оставляет колонку «Описание» пустой, а из схемы берёт description или title.

Вложенность и массивы

Вложенные поля записаны через точку (customer.name), а поля внутри элементов массива - через [] (items[].sku). Так сразу видно структуру и повторяемость.

Варианты oneOf и anyOf

Для полей с вариантами таблица перечисляет типы вариантов, но не раскрывает их внутренние поля. Если структура вариантов важна, опишите каждый вариант отдельной таблицей.

Внешние ссылки не загружаются

Ссылки $ref на другие файлы и адреса инструмент не разрешает: вставьте нужные определения в $defs той же схемы.

Частые вопросы

Отправляются ли мои данные на сервер?

Нет - 100%. Сайт целиком статический, у него нет серверной части. Разбор и построение выполняются в вашем браузере, образцы данных никуда не передаются.

Чем таблица по схеме отличается от таблицы по примеру?

По схеме в таблицу попадают описания, перечисления, ограничения и признак обязательности, заданные автором. По примеру тип и пример значения берутся из данных, а обязательность - из того, есть ли поле во всех объектах.

Как вставить таблицу в Confluence?

Выберите формат Confluence, скопируйте результат и вставьте в редактор в режиме разметки (Wiki markup): таблица со строкой заголовков создастся сразу. В новом редакторе можно вставить Markdown.

Какие форматы вывода есть?

Markdown (GitHub, GitLab, Notion, Obsidian), разметка Confluence, HTML-таблица и CSV для Excel и Google Таблиц. Заголовки столбцов можно выбрать на русском или английском.

Раскрываются ли ссылки $ref?

Да, внутренние: #/definitions/... и #/$defs/.... Внешние ссылки по адресам не загружаются. allOf объединяется в один набор полей.

Можно ли построить таблицу для массива объектов?

Да. Для массива берутся поля всех объектов в нём: они записываются с префиксом [] (например, items[].sku), а тип самого массива указывается как array<object>.

Курс «Проектирование API и интеграций»

Глубокое погружение в REST, gRPC, SOAP, проектирование баз данных и брокеры сообщений (Kafka, RabbitMQ). Делегирование рутины нейросетям (ИИ). Перестанете бояться технических собеседований и начнете говорить с разработчиками на одном языке. Курс собран так, чтобы пробить зарплатный потолок и вырасти в грейде - ученики тому подтверждение.