OpenAPI в JSON Schema: схемы спецификации для валидации

Как получить из OpenAPI один файл JSON Schema со всеми схемами — для проверки данных, генерации и тестов: nullable, example и ссылки переводятся автоматически.

Схемы данных из спецификации нужны и вне неё: валидировать сообщения в тестах, проверять конфигурации, генерировать формы. Для этого их удобно иметь отдельным файлом JSON Schema.

Как преобразовать

Откройте спецификацию в редакторе OpenAPI.
Выберите Файл → Преобразовать в → JSON Schema — схемы спецификации.
Сохраните результат или откройте в песочнице JSON Schema — там видна структура и можно сразу проверить пример.

JSON Schema со схемами спецификации в $defs — Все схемы спецификации — в $defs одного документа

Что делает конвертер

Все схемы components/schemas (или definitions из Swagger 2.0) переносятся в $defs, ссылки переписываются на #/$defs/….
Схемы из других файлов по $ref встраиваются; окно перечисляет встроенные файлы.
Для OpenAPI 3.0 и Swagger 2.0 — отличия от JSON Schema сглаживаются: nullable: true и x-nullable становятся типом с null, example — examples; discriminator, xml, externalDocs удаляются.
OpenAPI 3.1 уже использует JSON Schema 2020-12 — схемы переносятся как есть.

Как пользоваться результатом

Результат — JSON Schema 2020-12 только с $defs. Чтобы проверить документ по конкретной схеме, сошлитесь на неё в своей схеме ("$ref": "openapi-schemas.json#/$defs/Order") или временно добавьте в корень результата "$ref": "#/$defs/Order" и проверьте пример на вкладке «Проверка».

Пример

Схема OpenAPI 3.0:

Order:
  type: object
  properties:
    note: {type: string, nullable: true, example: "Позвонить заранее"}
    customer: {$ref: '#/components/schemas/Customer'}

в JSON Schema:

"Order": {
  "type": "object",
  "properties": {
    "note": {"type": ["string", "null"], "examples": ["Позвонить заранее"]},
    "customer": {"$ref": "#/$defs/Customer"}
  }
}

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

Попадают ли в результат параметры и тела запросов, описанные прямо в методах? Нет, переносятся схемы из components/schemas (и то, на что они ссылаются). Вынесите встроенные схемы в компоненты — это полезно и для самой спецификации.

Подойдёт ли результат для Ajv и других валидаторов? Да, это стандартная JSON Schema 2020-12.