Swagger Syntax: Wie man eine Modelldefinition von einer wiederverwendbaren Antwort referenziert

Question

Neu hier zu swagger. Ich bin durch die swagger primer gegangen und soweit ich das beurteilen kann, sollte mein Beispiel unten funktionieren.

Meine Antworttypen sind nur Arrays aus verschiedenen Strukturen (diese Strukturen sind im globalen Definitionsbereich definiert, um Aufblähen zu reduzieren, da sie möglicherweise verschachtelt sind und daher wiederverwendet werden).

Hier ist meine Definition:

consumes: 
    - application/json 
produces: 
    - application/json 
schemes: 
    - http 
swagger: '2.0' 
[...Additional details excluded...] 

paths: 
    /first: 
    get: 
     responses: 
     '200': 
      $ref: '#/responses/response1' 
    /second: 
    get: 
     responses: 
     '200': 
      $ref: '#/responses/response2' 


definitions: 
    ObjectA: 
    type: object 
    properties: 
     listOfObjBs: 
     type: array 
     items: 
      $ref: '#/definitions/ObjectB' 
    ObjectB: 
    type: object 
    properties: 
     listOfObjCs: 
     type: array 
     items: 
      $ref: '#/definitions/ObjectC' 
    ObjectC: 
    description: A build 
    type: object 
    properties: 
     someNumericData: 
     type: integer 
     format: int64 

responses: 
    response1: 
    description: There are 2 types of responses, this is the first kind. 
    schema: 
     type: object 
    headers: 
     data: 
     type: array 
     items: 
      $ref: '#/definitions/ObjectA' 
    response2: 
    description: This is the second kind. 
    schema: 
     type: object 
    headers: 
     data: 
     type: array 
     items: 
      $ref: '#/definitions/ObjectC' 

Allerdings bin ich in der Prahlerei Web-Editor in die Validierung Probleme läuft.

Schema Fehler bei Reaktionen [ 'Reaktionszeit1'] Header [ 'data'] Gegenstände sollten NICHT haben zusätzliche propertiesadditionalProperty:.. $ Ref

Semantische Fehler bei responses.response1.headers.data.items. $ ref Artikel $ refs können nicht mit einer der folgenden entsprechen: "#/Definitionen", "#/Parameter"

Schema Fehler bei Reaktionen [ 'response2'] Header [ 'data'].. Artikel sollten hat keine zusätzliche Eigenschaften additionalProperty:. $ Ref

Semantische Fehler bei responses.response2.headers.data.items $ ref Artikel $ Refs nicht eine der folgenden mithalten kann: "#/Definitionen", "#/Parameter "

Es sieht aus wie ich die json Referenzen falsch bin, aber ich bin mir nicht sicher, warum.

Ich habe auch versucht, response1 und response2 in den Definitionen zu setzen und direkt auf sie zu verweisen (z. B. die $ ref unter Pfade direkt auf '#/definitions/response1' anstatt auf '#/responses/response1'). Aber ich bekomme vom Herausgeber eine Fehlermeldung, dass ich Definitionen nicht direkt referenzieren kann.

Was ist der richtige Weg, um diese Definition zu strukturieren?

Answer 1

Antworten mit einem Körper haben eine schema. Um ein Modell Definition zu referenzieren, verwenden Sie die $ref Referenz als den Wert der schema:

responses: 
    response1: # <--- This node is on the same level as the status codes '200'/'404' etc. 
    description: There are 2 types of responses, this is the first kind. 
    schema: 
     $ref: '#/definitions/ObjectA' 

     # Or if the response is an array: 
     # type: array 
     # items: 
     # $ref: '#/definitions/ObjectA' 


    response2: 
    description: This is the second kind. 
    schema: 
     $ref: '#/definitions/ObjectC' 

Der Fehler in Ihrem Beispiel wurde die Referenzen unter headers setzen. Der Abschnitt headers definiert die HTTP-Header der Antwort, z. B. X-RateLimit oder Set-Cookie, und nicht die tatsächlichen Körper Payload.

response1: 
    description: There are 2 types of responses, this is the first kind. 
    schema: 
     type: object 

    # Errors were caused by this 
    headers: 
     data: 
     type: array 
     items: 
      $ref: '#/definitions/ObjectA'