Что на самом деле означает «требуется» в OpenAPI

Учитывая следующее определение OpenAPI, какие из перечисленных ниже объектов являются допустимыми. Просто 1. или 1. и 2.?

Person:
  required:
    - id
  type: object
  properties:
    id:
      type: string
  1. {"id": ""}
  2. {"id": null}
  3. {}

Это сводится к вопросу, означает ли «required = true» «ненулевое значение» или «должно присутствовать свойство».

Средство проверки схемы JSON на https://json-schema-validator.herokuapp.com/ сообщает это 2. недействительно, потому что null не удовлетворяет ограничению type: string. Обратите внимание, что он не жалуется, потому что id имеет значение null, а потому, что null не является строкой. НО насколько это актуально для OpenAPI / Swagger?


openapi swagger
person Marcel Stör    schedule 08.08.2017    source источник

Ответы (1)


arrow_upward
42
arrow_downward

Ключевое слово required в OpenAPI имеет то же значение, что и в Схема JSON:

обязательно

Экземпляр объекта действителен для этого ключевого слова, если его набор свойств содержит все элементы в значении массива этого ключевого слова.

Формулировка в последней спецификации схемы JSON ( хотя это не тот, который используется OpenAPI) более понятен:

Экземпляр объекта действителен для этого ключевого слова, если каждый элемент в массиве является именем свойства в экземпляре.

То есть required означает «свойство должно присутствовать» независимо от значения. type, format и т. Д. Значения свойства являются отдельными ограничениями, которые оцениваются отдельно от required, но вместе как объединенная схема.

В вашем примере:

  1. {"id": ""} действительно:

    • ✓ validates against required
    • ✓ значение "" проверяется на type: string

  2. {"id": null} НЕ действует:

    • ✓ validates against required
    • ✗ null НЕ проверяет type: string

  3. {} НЕ действует:

    • ✗ does NOT validate against required

Обратите внимание, что null как тип не поддерживается в OpenAPI, но OpenAPI 3.0 добавляет _ 17_, чтобы указать, что значение может быть null. Итак, {"id": null} будет проверяться на соответствие этой схеме OpenAPI 3.0:

Person:
  required:
    - id
  type: object
  properties:
    id:
      type: string
      nullable: true   # <----
person Helen    schedule 08.08.2017
comment
Отличный ответ, спасибо. Не ваша вина, что спецификация схемы JSON не соответствует концепции null в JavaScript / JSON. - person Marcel Stör; 09.08.2017
comment
Схема @ MarcelStör JSON имеет тип null, а схему, допускающую значение NULL, можно определить как {"type": ["string", "null"]}. Но OpenAPI не поддерживает type: null и вместо этого использует атрибут nullable. - person Helen; 09.08.2017