Как определить свойство, которое может быть строковым или нулевым в OpenAPI (Swagger)?

У меня есть файл схемы JSON, где одно из свойств определяется как string или null:

"type":["string", "null"]

При преобразовании в YAML (для использования с OpenAPI/Swagger) он становится:

type:
  - 'null'
  - string

но редактор Swagger показывает ошибку:

Ключ типа "схема" должен быть строкой

Каков правильный способ определения свойства nullable в OpenAPI?

Ответы

Ответ 1

type как массив типов

type:
  - string
  - 'null'

НЕ ДОПУСКАЕТСЯ в OpenAPI/Swagger (даже если он действителен в схеме JSON). Для ключевого слова OpenAPI type требуется один тип и не может быть массивом типов.

Поддержка null зависит от того, какую версию OpenAPI вы используете:

  • В OpenAPI 3.0 используйте ключевое слово nullable для определения типов с нулевым значением:

    type: string
nullable: true   # <----

  • OpenAPI 2.0 не поддерживает null как тип данных, поэтому, если вы используете 2.0, вам не повезло. Вы можете использовать type: string. Тем не менее, некоторые инструменты поддерживают x-nullable: true как расширение поставщика, хотя нули не являются частью спецификации OpenAPI 2.0.