Erweiterte JSON-Metadaten mit Swagger/OpenAPI

Question

Ich suche nach einer Möglichkeit, erweiterte Metadaten für JSON-Objekte zu deklarieren, die in einer API verwendet werden, die mit Swagger/OpenAPI angegeben wird (oder etwas Ähnliches, wenn ein anderes Format die angeforderten Features unterstützt).

Die Idee ist, diese Metadaten zu verwenden, um automatisch/teilweise Benutzerschnittstellen für die Bearbeitung dieser Daten zu generieren.

Eine Liste der gewünschten Features:

• Mehrsprachige Unterstützung für Benutzer lesbare Informationen wie Name, Beschreibung, Platzhalter, Beispiele - der Name und die Beschreibung der API-Spezifikation selbst als das, was der andere sein könnte Endbenutzer von zum Beispiel sollte ein CRUD-Editor sehen.

• Validation Metadaten
  Ich weiß, dass es ein verschiedenen Felder in Swagger/OpenAPI wie Minimum, Maximum, Muster etc. - aber es gibt keine Möglichkeit spezifische (mehrsprachig) Fehlermeldungen für die Validierungen (So etwas wie „A angeben, Der Benutzername muss aus Buchstaben und nur Zahlen "und den Übersetzungen in mehrere Sprachen bestehen. Oder mehrere Muster übereinstimmen (miteinander verbundene Fehlermeldung daran).

  Eine weitere Methode zur Validierung könnte ein API-Aufruf auf seine eigenen seine

• Relation Metadaten für Beispiel (wie der Prüfung, ob eine E-Mail oder Benutzername verfügbar ist), dass das ID-Feld auf die ID eines anderen tatsächlich referes Objekt (mit eigenen Metadaten).

Answer 1

Die OpenAPI (fka. Swagger) Spezifikation kann mit x- Eigenschaften erweitert werden (siehe Specification Extension die Spezifikation). Diese x- Eigenschaften werden von Standard-OpenAPI-Parsern ignoriert.

Sie können Ihre eigenen Eigenschaften fast überall in der Spezifikationsdatei selbst in JSON-Schemadefinitionen definieren, aber Sie müssen einen eigenen Parser schreiben, um sie zu verwenden und/oder Werkzeuge wie Swagger UI zu modifizieren (was ziemlich einfach ist) tun), um sie in solchen Werkzeugen zu sehen.

Hier ist ein Beispiel mit einigen x-Spannungen in Definitionen:

swagger: "2.0" 

info: 
    version: 1.0.0 
    title: X-tension example 
    description: Using x- properties to extend the OpenAPI specification 
    x-example: we can put x-tension almost anywhere in the specification 

paths: {} 

definitions: 
    User: 
    properties: 
     id: 
     type: string 
     name: 
     type: string 
     maxLength: 50 
     minLength: 10 
     x-validation: 
      multiLingualMessage: 
      en: Name's length must be between <minLength> and <maxLength> 
      fr: La longeur de Name doit être comprise entre <minLength> et <maxLength> 
     friends: 
     type: array 
     description: An array of UserId 
     items: 
      type: string 
      x-reference: 
      type: User 

Diese OpenAPI-Spezifikation vom Herausgeber gültig betrachtet wird: es die x- Eigenschaften ignoriert.

Dieses Beispiel ist nur eine Illustration von x- Eigenschaften und hat nicht die Absicht, alle in der Frage aufgeführten Anwendungsfälle zu lösen.