Ich muss mit Swagger eine API dokumentieren, die sowohl als Eingabe als auch als Ausgabe Maps von Objekten verwendet, indiziert durch Stringtasten.
Beispiel:
%Vor%"foo" und "bar" können beliebige Zeichenfolgenschlüssel sein, aber sie sollten innerhalb der Schlüsselgruppe eindeutig sein.
Ich weiß, dass ich mit Swagger ein Array von Objekten definieren kann, aber dies ergibt eine andere API, da wir dann etwas haben würden:
%Vor%Ich habe die "API-Spezifikation öffnen" - "Unterstützung für Kartendatentypen # 38 hinzufügen" Seite. Soweit ich es verstehe, empfiehlt es die Verwendung von additionalProperties, aber es scheint nicht zu meinem Bedarf zu passen (oder es funktioniert nicht mit Swagger UI 2.1.4, die ich verwende). Habe ich etwas verpasst?
Bisher habe ich das folgende Workaround gefunden (in Swagger JSON):
%Vor%Das macht fast den Job, aber der Leser muss verstehen, dass "key" eine beliebige Zeichenfolge sein kann und mehrmals wiederholt werden kann.
Gibt es einen besseren Weg, um das zu erreichen, was ich brauche?
Die Verwendung von additionalProperties ist die richtige Methode, um hashamp mit der OpenAPI (fka. Swagger) -Spezifikation zu beschreiben, aber die Swagger UI macht sie vorerst nicht rendern.
Das Problem wird hier Ссылка
verfolgt In der Zwischenzeit können Sie mit diesem Trick eine nicht benötigte Eigenschaft ( default im folgenden Beispiel) desselben Typs von Kartenobjekten definieren und einen Hinweis in der Beschreibung geben:
Diese Beschreibung ändert nicht den API-Vertrag und verbessert die Dokumentation.
Wenn ich es richtig verstehe, besteht das grundlegende Problem darin, dass es keine allgemein akzeptierte JSON-Zuordnung für eine Java-Map gibt, insbesondere wenn der Schlüssel komplexer als eine Zeichenfolge ist. Ich habe gesehen, dass GSON einen Ansatz verfolgt (behandeln Sie den Schlüssel als ein Objekt), während Jackson einen anderen (serialisiert den Schlüssel zu einer Zeichenkette) nimmt. Das C # -Aquivalent zu einer Map (einem Dictionary) verwendet einen dritten Ansatz (jeden Eintrag als eigenständiges Schlüsselwertobjekt mit den Eigenschaften "Key" und "Value" zu behandeln). Da Swagger versucht, der Sprache und dem Serialisierer gegenüber agnostisch zu sein, stellt dies eine unmögliche Position dar.
Tags und Links dictionary swagger