Swagger: Beschreibung mit Ref hinzufügen

Ich möchte eine Beschreibung zu einer Objekteigenschaft hinzufügen, auf die seine Definition verwiesen wird. So etwas Ähnliches:Swagger: Beschreibung mit Ref hinzufügen

 newCreditCard: 
     type: object 
     properties: 
      billingPhone: 
      description: Phone number of the card holder 
      $ref: "#/definitions/PhoneNumber"

Aber der Herausgeber warnt, dass die Beschreibung Eigenschaft wird übersprungen:

Extra JSON Reference properties will be ignored: description

ich eine weniger elegante Abhilfe gefunden haben, die für den Editor funktioniert, aber nicht für die Swagger UI (nicht sicher, dass ist

der jüngsten Update auf 3.0.2 Version des Swagger UI) auf Grund können Sie es in Ihrem Swaggers Spezifikation

 newCreditCard: 
     type: object 
     properties: 
      billingPhone: 
      description: Phone number of the card holder 
      allOf: 
      - $ref: "#/definitions/PhoneNumber"

Wie?

Danke für die Hilfe!

Quelle

2017-03-24 Jonathan Huet

Wenn Sie etwas auf die gleiche Ebene von $ref hinzufügen, wird es ignoriert.

json $ ref Definition https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3

richtige Weg ist die Beschreibung in referenzierte Objekt zu schaffen.

Quelle

2017-08-06 08:43:05

Sie könnten einfach die description Eigenschaft in die Definition von PhoneNumber verschieben. Ihr Original-Beitrag zeigt nicht, wie Sie PhoneNumber definiert haben, aber dieser Schnipsel validiert ohne Warnungen:

definitions: 
    phoneNumber: 
    type: string 
    description: Phone number of the card holder 

    newCreditCard: 
    type: object 
    properties: 
     billingPhone: 
     $ref: "#/definitions/phoneNumber"

Wenn diese Antwort ist nicht das, was Sie suchen, benutzen Sie bitte die Frage neu formulieren. Wir müssen wissen, was Sie erreichen wollen.

Quelle

2017-03-24 19:39:01

Angenommen, der Zweck von $ ref besteht darin, eine Definition wiederzuverwenden, dann sollte die einzelne phoneNumber-Definition für den "Karteninhaber", ein "Handy", ein "Zuhause", ein "Fax", ein "Arbeit" verfügbar sein "Nummer ... Sie bekommen den Punkt. Diese Beschreibungen können nicht alle in der phoneNumber-Definition berücksichtigt werden, sondern müssten auf die Definitionen angewendet werden, die * die * phoneNumber-Definition referenzieren. Es scheint, dass Swagger (oder ist es die zugrunde liegende JSONReference-Spezifikation?) Dies schwierig oder zumindest nicht offensichtlich macht. –

Addendum: Dieser Thread gibt an, dass es sich um eine Einschränkung der JSONReference-Spezifikation handelt - https://groups.google.com/forum/#!topic/swagger-swaggersocket/ewgimdO2cOI. Stimmen Sie mit allen Bewertungen überein, dass es eine Schande ist, weil es die Wiederverwendung unter bestimmten Umständen wirklich unmöglich macht. –

Das Ziel der Trennung der Beschreibungseigenschaft vom 'phoneNumber'-Modell besteht darin, mehrere Eigenschaften mit unterschiedlicher Beschreibung zuzulassen, die dasselbe Modell verwenden. Zum Beispiel das billingPhone "Telefonnummer des Karteninhabers", aber zum Beispiel für ein Fax sollte die Beschreibung "Fax des Hauptbüros" sein. Für beide ist die gesamte Modelldefinition die gleiche wie für die Beschreibung. Danke für die Antwort und Hilfe –

Swagger: Beschreibung mit Ref hinzufügen

Antwort

Verwandte Themen