Перейти к содержимому
Numio

Конвертер схемы JSON в спецификации OpenAPI — Numio

Преобразует JSON Schema (draft-04 и новее) в OpenAPI 3.0 Schema Object. Массивы type, содержащие "null", превращаются в "nullable: true", const — в enum из одного элемента, а examples — в одиночный example.

Вы проверяете данные схемой draft-07, и та же модель нужна в разделе components/schemas документа OpenAPI 3.0.

JSON Schema

Open API Schema

Когда пригодится

  • Вы проверяете данные схемой draft-07, и та же модель нужна в разделе components/schemas документа OpenAPI 3.0.
  • Ваши инструменты OpenAPI 3.0 не принимают "type": ["string", "null"], и nullable-поля нужно переписать.

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

  1. Вставьте JSON Schema в панель JSON Schema; это должен быть корректный JSON, так как страница разбирает его перед отправкой.
  2. Схема отправляется на /api/json-schema-to-openapi-schema и конвертируется на сервере; панель показывает соответствующее уведомление.
  3. Скопируйте результат из панели Open API Schema и поместите его в components/schemas вашего файла OpenAPI.

JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "kind": { "const": "invoice" },
    "total": { "type": ["number", "null"], "exclusiveMinimum": 0 },
    "notes": { "type": "string", "examples": ["Net 30"] }
  },
  "required": ["kind"]
}

OpenAPI 3.0 Schema Object

{
  "type": "object",
  "properties": {
    "kind": {
      "enum": [
        "invoice"
      ]
    },
    "total": {
      "type": "number",
      "exclusiveMinimum": true,
      "nullable": true,
      "minimum": 0
    },
    "notes": {
      "type": "string",
      "example": "Net 30"
    }
  },
  "required": [
    "kind"
  ]
}

Подробности и ограничения

Страница отправляет ваши данные на серверный маршрут (/api/json-schema-to-openapi-schema) для конвертации; они обрабатываются не только в браузере. API-маршруты Next.js по умолчанию принимают тело запроса размером до 1 МБ.

Ключевое слово $schema удаляется. Числовые exclusiveMinimum/exclusiveMaximum переписываются в форму OpenAPI 3.0: minimum/maximum плюс булев флаг.

Значения $ref остаются как есть, а definitions не переносятся в components/schemas, поэтому пути ссылок нужно исправить самостоятельно.

Целевая версия — OpenAPI 3.0. OpenAPI 3.1 уже напрямую использует JSON Schema и обычно не требует конвертации.

FAQ

Как конвертируются nullable-типы?

Массив type вроде ["number", "null"] становится "type": "number" с "nullable": true, как в примере.

Разрешаются ли ссылки $ref?

Нет. Страница не выполняет разыменование; "$ref": "#/definitions/Tag" и блок definitions копируются без изменений.

Что происходит с const и examples?

const становится enum с одним значением, а массив examples заменяется одиночным example, взятым из его первого элемента.

Спецификации и справка