Почему " additionalProperties` - это способ представления словаря / карты в Swagger / OpenAPI 2.0

хотя я видел примеры в OpenAPI spec:

type: object
additionalProperties:
  $ref: '#/definitions/ComplexModel'

это не очевидно для меня почему использование additionalProperties правильная схема на карте/словарь.

Это также не помогает, что единственная конкретная вещь, которую спецификация должна сказать о additionalProperties - это:

следующие свойства взяты из определения схемы JSON, но их определения были скорректированы на Swagger Спецификация. Их определение совпадает с определением из схемы JSON, только если исходное определение ссылается на определение схемы JSON, вместо этого используется определение объекта схемы.

  • предметы
  • все
  • свойства
  • additionalProperties
12
dictionary hash mapping openapi swagger

2 ответов

Чен, я думаю,ваш ответ является правильным.

некоторые дополнительные сведения, которые могут быть полезны:

в JavaScript, который был исходным контекстом для JSON, объект похож на хэш-карту строк для значений, где некоторые значения являются данными, другие-функциями. Можно рассматривать каждую пару имя-значение как свойство. Но JavaScript не имеет классов, поэтому имена свойств не предопределены, и каждый объект может иметь свой собственный независимый набор свойства.

схема JSON использует properties ключевое слово для проверки пар имя-значение, которые известны заранее; и использует additionalProperties (или patternProperties, не поддерживается в OpenAPI 2.0) для проверки свойств, которые не известны.

для ясности:

  • имена свойств или" ключи " на карте должны быть строками. Это не могут быть числа или любое другое значение.
  • как вы сказали, имена свойств должны быть уникальным. К сожалению Спецификация JSON строго не требует уникальности, но уникальность рекомендуется и ожидается большинством реализаций JSON. Больше фона здесь.
  • properties и additionalProperties можно использовать отдельно или в комбинации. Когда additionalProperties используется отдельно, без свойств, объект по существу функционирует как map<string, T> где T является типом, описанным в подразделе схемы additionalProperties. Возможно, это поможет ответить на ваш первоначальный вопрос.
  • когда оценка объекта по одной схеме, если имя свойства совпадает с одним из указанных в properties, его стоимость должна быть действительна на суб-схеме предусмотрено, что собственность. The additionalProperties вложенная схема, если она указана, будет использоваться только для проверки свойств, которые не входит в properties карта.
  • есть некоторые ограничения additionalProperties как реализовано в основных библиотеках Java Swagger. Я задокументировал эти ограничения здесь.
22

Первое, что я нашел лучшее объяснение additionalProperties:

для объекта, если это задано, в дополнение к свойствам, определенным в properties все остальные имена свойств, не допускаются. Их значения должны соответствовать приведенному здесь Объекту схемы. Если это не задано, никаких других свойств, кроме тех, которые определены в properties разрешено.

так вот как я понял этот:

используя properties, мы можем определите известный набор свойств, подобных в Python namedtuple, однако, если мы хотим иметь что-то более похожее питона дикт, или любой другой хэш / карта, где мы не можем указать, сколько ключей есть и что они заранее, мы должны использовать additionalProperties.

additionalProperties будет соответствовать любому имени свойства (которое будет действовать как и $ref или type будет схемы dictзначение, и так как не должно быть более одного свойства с одинаковым именем для каждого данного объекта, мы получим принудительное применение уникальных ключей.

обратите внимание, что в отличие от Python dict который принимает любое неизменяемое значение в качестве ключа, так как ключи здесь по сути являются именами свойств, они должны быть строками. (Спасибо Тэд Эпштейн за это разъяснение). Это ограничение можно отследить до pair := string : value на спецификация json.

15