Wie xml-Wrapper-Element in Swagger-ui

Question

Ich bin mit Prahlerei-ui Version 2.2.8

Unsere bestehenden API zu verhindern, kann application/json sowie application/xml erzeugen.
Für ein Rekordergebnis in json es produziert:

{ 
    "person": { 
    "id": 23, 
    "name": "John" 
    } 
} 

und für XML produziert es:

{ 
    "person": { 
     "type": "object", 
     "properties": { 
      "person": { 
       "$ref": "#/definitions/personfields" 
      } 
     } 
    } 
} 

Bei Betrachtung in:

<person> 
    <id>23</id> 
    <name>John</name> 
</person> 

Mein Prahlerei-Schema dafür ist, Swagger-Ui das JSON-Modell sieht gut aus. Doch das XML-Modell wird:

<person> 
    <person> 
    <id>1</id> 
    <name>string</name> 
    </person> 
</person> 

Gibt es eine Möglichkeit, diese doppelte <Person> zu verhindern, aber immer noch das richtige JSON Ergebnis zu erhalten?

Answer 1

In OpenAPI Begriffe, Ihre JSON und XML-Modelle unterscheiden – die JSON-Version von

<person> 
    <id>23</id> 
    <name>John</name> 
</person> 

{ 
    "id": 23, 
    "name": "John" 
} 

ohne Wrapper Eigenschaft person wäre.

Sie können kein einziges Schema für Modelle haben, die sich auf diese Weise unterscheiden.

Was Sie tun können, ist Ihr Modell als Freiform-Objekt definieren (type: object ohne properties) und die JSON/XML-Antwort Beispiele statt – angeben, aber in diesem Fall verlieren Sie die Möglichkeit, die Objekteigenschaften zu definieren.

definitions: 
    person: 
    type: object 

paths: 
    /person: 
    get: 
     produces: 
     - application/json 
     - application/xml 
     responses: 
     200: 
      description: OK 
      schema: 
      $ref: '#/definitions/person' 
      examples: 
      application/json: | 
       { 
       "person": { 
        "id": 23, 
        "name": "John" 
       } 
       } 
      application/xml: | 
       <person> 
       <id>23</id> 
       <name>John</name> 
       </person>    

Hinweis: Wenn Sie Swagger UI verwenden, Version 3.0.x verwenden becase 2.2.x nicht solche Beispiele korrekt anzeigt.

In der nächsten Version – OpenAPI 3.0 (die RC im Moment des Schreibens ist) – wird es möglich sein, unterschiedliche Schemata für unterschiedliche Antwort MIME-Typen angeben. So in 3.0 Ihr Beispiel wird beschrieben als:

paths: 
    /person: 
    get: 
     responses: 
     '200': 
      description: OK 
      content: 
      application/json: 
       $ref: '#/components/definitions/PersonJson'    
      application/xml: 
       $ref: '#/components/definitions/Person' 

components: 
    definitions: 

    # XML object schema 
    Person: 
     type: object 
     properties: 
     id: 
      type: integer 
      example: 23 
     name: 
      type: string 
      example: John 
     xml: 
     name: person 

    # JSON object schema with a wrapper property "person" 
    PersonJson: 
     type: object 
     properties: 
     person: 
      $ref: '#/components/definitions/Person'