webentwicklung-frage-antwort-db.com.de

Swagger-komplexes Antwortmodell mit dynamischen Schlüsselwert-Hashkarten

Ich kämpfe mit der Syntax von swagger, um einen Antworttyp zu beschreiben. Was ich versuche zu modellieren, ist eine Hash-Map mit dynamischen Schlüsseln und Werten. Dies ist erforderlich, um eine Lokalisierung zu ermöglichen. Die Sprachen können variieren, es sollte jedoch immer Englisch angegeben werden.

Die Antwort würde in JSON folgendermaßen aussehen:

{
  id: "1234",
  name: {
    en: "english text",
    de: "Deutscher Text"
  }
}

Mein erster Versuch sah so aus, aber ich habe keine Ahnung, wie ich den Namen für den Namen schreiben soll. AdditionalProperties scheint ein Schlüssel zu sein, aber ich kann meinen Kopf nicht darum wickeln. Auch die Anforderung an englischen Text ist mir in dieser Syntax ein Rätsel, und das Beispiel scheint auch nicht wie erwartet zu funktionieren. Es erzeugt ein leeres $ fold: in der Benutzeroberfläche.

delayReason:
  type: object
  properties:
    id:
      type: string
      description: Identifier for a delay reason.
    name:
      type: object
      additionalProperties: 
        type: string
  required: [id, name]
  example:
    id: 123
    name: 
      en: english text
      de: Deutscher Text

Aber das erzeugt:  swagger editor result

Es gibt auch keinen Hinweis darauf, dass das Ergebnis einen Sprachcode als Schlüssel und den Text als Wert der Hash-Map haben wird.

hashmapswaggerswagger-2.0swagger-editor
12
user1736217

Es scheint, dass Sie mindestens drei verschiedene Fehler und/oder Einschränkungen haben:

  1. Weder der Swagger-Editor noch die Swagger-UI geben im Dokumentationsformat Hinweise darauf, dass additionalProperties in Ihrem Objektschema zulässig ist. Selbst wenn Sie additionalProperties korrekt verwendet haben und vom Swagger-Parser erkannt werden, wird dies in diesen Dokumentationsformaten nicht angezeigt. Sie müssen dieses Detail zu Ihrem Schema description hinzufügen, damit Benutzer verstehen, dass sie zusätzliche Zeichenfolgeeigenschaften hinzufügen können.

    Anmerkung: Sie erwarten wahrscheinlich auch, dass die zusätzlichen Eigenschaftsnamen einer Konvention folgen, z. ein aus zwei Buchstaben bestehender Sprachcode. Während Sie für das vollständige JSON-Schema dies mit patternProperties angeben können, wird dies im Swagger-Schemaobjekt nicht unterstützt. Sie sollten dies also erneut in Ihrer Schemabeschreibung angeben.

  2. Das Swagger-Editor-Format zeigt manchmal diese ungerade "fold:" - Eigenschaft. Ich habe es heute morgen gesehen, seltsamerweise kann ich es nicht reproduzieren. Es könnte heute ein Hotfix sein. Aber egal, es ist sicherlich ein Fehler und spezifisch für Swagger-Editor. Es sollte sich nicht auf die Generierung von Downstream-Code oder die standardmäßige Swagger-UI auswirken, die die API-Dokumentation zur Laufzeit den Client-Entwicklern zur Verfügung stellt. (Obwohl der Dokumentationsbereich im Swagger-Editor der Swagger-UI ähnelt, ist dies eine separate Implementierung.)

  3. Die Verwendung von additionalProperties in Swagger hat einige subtile, aber erhebliche Einschränkungen. Während Helen s Beispiel keine sichtbaren Fehler zeigt, kann der Swagger-Parser dieses Schema nicht korrekt verarbeiten. Es wird entweder Ihre explizit deklarierte en -Eigenschaft ignorieren oder additionalProperties ignorieren! 

Diese letzte Ausgabe beruht auf einem Konstruktionsfehler in Swagger-Model, einer der Kernkomponenten des Swagger-Java-Stacks (einschließlich Swagger-Codegen). In bestimmten Kontexten definierte Schemas können mit einer Kombination aus properties und additionalProperties arbeiten. In anderen Zusammenhängen definierte Schemas können jedoch nicht. 

Wir haben hier ausführlich dokumentiert .

Die gute Nachricht: Mit einem kleinen Tweak können wir Helens Beispiel richtig funktionieren lassen. Wir müssen nur das verschachtelte Objektschema in seine eigene Definition auf oberster Ebene extrahieren. Ich werde es LocalizedName nennen:

definitions:
  delayReason:
    type: object
    properties:
      id:
        type: string
        description: Identifier for a delay reason.
      name:
        $ref: "#/definitions/LocalizedName"
    required: [id, name]
    example:
      id: '123' # Note the quotes to force the value as a string
      name: 
        en: English text
        de: Deutscher Text

  LocalizedName:
    type: object
    description: A hashmap with language code as a key and the text as the value.
    properties:
      en:
        type: string
        description: English text of a delay reason.
    required: [en]
    additionalProperties: 
      type: string
12
Ted Epstein

Ihre Verwendung von additionalProperties ist korrekt und Ihr Modell ist korrekt.

zusätzlicheEigenschaften

In Swagger/OpenAPI werden Hash-Schlüssel als Zeichenfolgen angenommen, sodass der Schlüsseltyp nicht explizit definiert wird. additionalProperties definiert den Typ der Hashmap-Werte. Also dieses Schema

type: object
additionalProperties: 
  type: string

definiert eine Zeichenfolge-zu-Zeichenfolge-Zuordnung:

{
  "en": "English text",
  "de": "Deutscher Text"
}

Wenn Sie eine Zeichenfolge-Ganzzahl-Zuordnung benötigen, z.

{
  "en": 5,
  "de": 3
}

sie würden additionalProperties als Werttyp integer definieren:

type: object
additionalProperties: 
  type: integer

Erforderlicher Schlüssel in einer Hashmap

So definieren Sie en als erforderlichen Schlüssel in der Hashmap:

type: object
properties:
  en:
    type: string
required: [en]
additionalProperties: 
  type: string

Vollständiges Beispiel

definitions:
  delayReason:
    type: object
    properties:
      id:
        type: string
        description: Identifier for a delay reason.
      name:
        type: object
        description: A hashmap with language code as a key and the text as the value.
        properties:
          en:
            type: string
            description: English text of a delay reason.
        required: [en]
        additionalProperties: 
          type: string
    required: [id, name]
    example:
      id: '123' # Note the quotes to force the value as a string
      name: 
        en: English text
        de: Deutscher Text

Es gibt auch keinen Hinweis darauf, dass das Ergebnis einen Sprachcode als Schlüssel und den Text als Wert der Hash-Map haben wird.

Solche Dinge können in der description verbal dokumentiert werden.

das Beispiel scheint auch nicht wie erwartet zu funktionieren. Es erzeugt ein leeres $ fold: in der Benutzeroberfläche.

Nicht sicher, was das Problem mit Ihrer ursprünglichen Spezifikation war, aber die oben angegebene Spezifikation ist gültig und sieht gut aus im Swagger Editor .

Model schema in Swagger Editor

12
Helen

Wenn Sie sich noch in der Entwurfsphase befinden, können Sie anstelle von dynamischen Schlüsseln alle anderen Sprachverweise in einem Array mit der folgenden Struktur pushen:

{
"launguage":"en"
"text":"Hello World"
}

Das würde die Dinge sehr vereinfachen, und da Sie sich nicht auf additionalProperties verlassen, können Ihre generierten Client-Bibliotheken dies leichter verdauen.

0
Sanket Berde