web-dev-qa-db-fra.com

Pourquoi `additionalProperties` est le moyen de représenter Dictionary / Map dans Swagger / OpenAPI 2.0

Bien que j'aie vu les exemples dans la spécification OpenAPI :

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

il n'est pas évident pour moi pourquoi l'utilisation de additionalProperties est le schéma correct pour une carte/dictionnaire.

Cela n'aide pas non plus que la seule chose concrète que la spécification ait à dire sur additionalProperties est:

Les propriétés suivantes sont extraites de la définition de schéma JSON mais leurs définitions ont été ajustées à la spécification Swagger. Leur définition est la même que celle du schéma JSON, uniquement lorsque la définition d'origine fait référence à la définition de schéma JSON, la définition d'objet de schéma est utilisée à la place.

  • articles
  • tous
  • propriétés
  • additionalProperties
dictionaryhashmappingswaggeropenapi
23
Chen Levy

Chen, je pense que votre réponse est correcte.

Quelques informations supplémentaires qui pourraient être utiles:

En JavaScript, qui était le contexte d'origine pour JSON, un objet est comme une carte de hachage de chaînes à valeurs, où certaines valeurs sont des données, d'autres sont des fonctions. Vous pouvez considérer chaque paire nom-valeur comme une propriété. Mais JavaScript n'a pas de classes, donc les noms de propriété ne sont pas prédéfinis, et chaque objet peut avoir son propre ensemble indépendant de propriétés.

Le schéma JSON utilise le mot clé properties pour valider les paires nom-valeur connues à l'avance; et utilise additionalProperties (ou patternProperties, non pris en charge dans OpenAPI 2.0) pour valider les propriétés qui ne sont pas connues.

Pour plus de clarté:

  • Les noms de propriété, ou "clés" dans la carte, doivent être des chaînes. Ils ne peuvent pas être des nombres ou toute autre valeur.
  • Comme vous l'avez dit, les noms de propriété doivent être uniques. Malheureusement, la spécification JSON ne nécessite pas strictement l'unicité, mais l'unicité est recommandée et attendue par la plupart des implémentations JSON. Plus d'informations ici .
  • properties et additionalProperties peuvent être utilisés seuls ou en combinaison. Lorsque additionalProperties est utilisé seul, sans propriétés, l'objet fonctionne essentiellement comme map<string, T> où T est le type décrit dans le sous-schéma additionalProperties. Peut-être que cela aide à répondre à votre question initiale.
  • Lors de l'évaluation d'un objet par rapport à un schéma unique, si un nom de propriété correspond à l'un de ceux spécifiés dans properties, sa valeur doit uniquement être valide par rapport au sous-schéma fourni pour cette propriété. Le sous-schéma additionalProperties, s'il est fourni, ne sera utilisé que pour valider les propriétés qui ne sont pas incluses dans le properties plan.
  • Il y a quelques limitations de additionalProperties telles qu'implémentées dans le noyau de Swagger Java. J'ai documenté ces limitations ici .
29
Ted Epstein

Tout d'abord, j'ai trouvé un meilleure explication pour additionalProperties :

Pour un objet, s'il est donné, en plus des propriétés définies dans properties, tous les autres noms de propriété sont autorisés. Leurs valeurs doivent chacune correspondre à l'objet de schéma donné ici. Si ce n'est pas donné, aucune autre propriété que celles définies dans properties n'est autorisée.

Voici donc comment j'ai finalement compris cela:

En utilisant properties, nous pouvons définir un ensemble connu de propriétés similaires à Python's namedtuple , cependant si nous souhaitons avoir quelque chose de plus comme Python's dict , ou tout autre hash/map où nous ne pouvons pas spécifier combien de clés il y a ni ce qu'elles sont à l'avance, nous devons utiliser additionalProperties.

additionalProperties correspondra à n'importe quel nom de propriété (qui agira comme clé de dict et $ref ou type sera le schéma de la valeur de dict, et comme il ne devrait pas y avoir plus d'une propriété avec le même nom pour chaque objet donné, nous obtiendrons l'application de clés uniques .

Notez que contrairement à dict de Python qui accepte toute valeur immuable comme clé, puisque les clés ici sont essentiellement des noms de propriété, elles doivent être des chaînes. (Merci Ted Epstein pour cette clarification). Cette limitation peut être retracée jusqu'à pair := string : value dans spécification json .

23
Chen Levy