Warum mit "additionalProperties" Dictionary/Map in Swagger/OpenAPI 2.0 dargestellt werden kann




hash mapping (2)

Als erstes habe ich eine bessere Erklärung für additionalProperties :

Wenn dies für ein Objekt angegeben ist, sind zusätzlich zu den in properties definierten properties alle anderen Eigenschaftsnamen zulässig. Ihre Werte müssen jeweils mit dem hier angegebenen Schemaobjekt übereinstimmen. Wenn dies nicht angegeben wird, sind keine anderen Eigenschaften als die in properties definierten zulässig.

Also hier ist, wie ich das endlich verstanden habe:

Mithilfe von properties können wir einen bekannten Satz von Eigenschaften definieren, der dem namedtuple von Python ähnelt . Wenn wir jedoch mehr wie Pythons Diktat oder einen anderen Hash / eine andere Map haben möchten, können wir nicht angeben, wie viele Schlüssel es gibt und in welchen sie sich befinden Vorab sollten wir additionalProperties .

additionalProperties stimmt mit jedem Eigenschaftsnamen überein (der als Schlüssel des dict , und $ref oder type ist das Schema des dict , und da nicht mehr als eine Eigenschaft mit demselben Namen für jede Eigenschaft vorhanden sein sollte Bei gegebenem Objekt erhalten wir die Durchsetzung eindeutiger Schlüssel.

Beachten Sie, dass es sich im Gegensatz zu Pythons dict , das einen unveränderlichen Wert als Schlüssel akzeptiert, um Zeichenfolgen handeln muss, da die Schlüssel hier im Wesentlichen Eigenschaftsnamen sind. (Danke Ted Epstein für die Klarstellung). Diese Einschränkung kann auf pair := string : value in der json-Spezifikation zurückgeführt werden .

Obwohl ich die Beispiele in der OpenAPI-Spezifikation gesehen habe :

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

Mir ist nicht klar, warum die Verwendung von additionalProperties das richtige Schema für eine Karte / ein Wörterbuch ist.

Es hilft auch nicht, dass das einzige, was die Spezifikation über additionalProperties zu sagen hat, ist:

Die folgenden Eigenschaften stammen aus der JSON-Schemadefinition, ihre Definitionen wurden jedoch an die Swagger-Spezifikation angepasst. Ihre Definition ist dieselbe wie die aus dem JSON-Schema, nur wenn die ursprüngliche Definition auf die JSON-Schemadefinition verweist, wird stattdessen die Schemaobjektdefinition verwendet.

  • Artikel
  • alle
  • Eigenschaften
  • additionalProperties

Chen, ich denke deine Antwort ist richtig.

Einige weitere Hintergrundinformationen, die hilfreich sein könnten:

In JavaScript, dem ursprünglichen Kontext für JSON, ähnelt ein Objekt einer Hash-Zuordnung von Zeichenfolgen zu Werten, wobei einige Werte Daten und andere Funktionen sind. Sie können sich jedes Name-Wert-Paar als eine Eigenschaft vorstellen. Da JavaScript jedoch keine Klassen hat, sind die Eigenschaftsnamen nicht vordefiniert, und jedes Objekt kann über einen eigenen Satz von Eigenschaften verfügen.

Das JSON-Schema verwendet das Schlüsselwort properties , um im Voraus bekannte Name-Wert-Paare zu überprüfen. und verwendet additionalProperties (oder patternProperties , die in OpenAPI 2.0 nicht unterstützt werden), um nicht bekannte Eigenschaften zu überprüfen.

Zur Klarheit:

  • Die Eigenschaftsnamen oder "Schlüssel" in der Map müssen Zeichenfolgen sein. Sie können keine Zahlen oder andere Werte sein.
  • Wie Sie sagten, sollten die Eigenschaftsnamen eindeutig sein. Leider erfordert die JSON-Spezifikation nicht unbedingt Eindeutigkeit, aber Eindeutigkeit wird empfohlen und von den meisten JSON-Implementierungen erwartet. Mehr Hintergrund here .
  • properties und additionalProperties properties können einzeln oder in Kombination verwendet werden. Wenn additionalProperties alleine ohne Eigenschaften verwendet wird, fungiert das Objekt im Wesentlichen als map<string, T> wobei T der Typ ist, der im Unterschema additionalProperties beschrieben ist. Vielleicht hilft das, Ihre ursprüngliche Frage zu beantworten.
  • Wenn ein Objekt anhand eines einzelnen Schemas ausgewertet wird und ein Eigenschaftsname mit einem der in properties angegebenen Namen übereinstimmt, muss sein Wert nur für das für diese Eigenschaft bereitgestellte Teilschema gültig sein. Das Teilschema additionalProperties , sofern angegeben, nur zum Überprüfen von Eigenschaften verwendet, die nicht in der properties .
  • Es gibt einige Einschränkungen von additionalProperties wie sie in Swaggers Java-Kernbibliotheken implementiert sind. Ich habe diese Einschränkungen here dokumentiert.




openapi