Wie fügt man ein JSON-Array von Objekten in Swagger ein?

Question

Derzeit Swagger.io verwenden, um meine API zu dokumentieren. Versuchen zu verstehen, wie das Senden eines benutzerdefinierten JSON-Objekts dokumentiert wird.

• PUT auf einer Sammlung/some_endpoint

• MIME: application/json

• Custom Data:

  [ 
      {"keyA": "a value", "keyB": "b value"}, 
      {"keyA": "a value", "keyB": "b value"} 
  ] 
  

Ist es möglich, dies in Swagger zu dokumentieren ?

/some_endpoint: 
    put: 
     description: | 
     desc goes here 
     parameters: 
     - name: guid 
      in: query 
      description: 
      required: true 
      type: string 
      format: string   
     # Expected responses for this operation 
     responses: 
     # Response code 
     200: 
      description: Successful response 

Answer 1

JSON Daten in dem Anforderungs Körper gesendet werden, so braucht es als body parameter definiert werden. Die Körperstruktur wird unter Verwendung des Schlüsselwortes schema (nicht type) beschrieben. In Ihrem Beispiel sind die Daten ein Array von Objekten, wobei jedes Objekt die Eigenschaften keyA und keyB hat.

paths: 
    /some_endpoint: 
    put: 
     summary: Puts something 
     description: | 
     desc goes here 
     consumes: 
     - application/json 
     parameters: 
     - in: body 
      name: body 
      required: true 
      schema: 
      type: array 
      items: 
       $ref: '#/definitions/MyObject' 
      # If you need to define array size constraints: 
      minItems: 1 
      minItems: 10 

definitions: 
    MyObject: 
    type: object 
    properties: 
     keyA: 
     type: string 
     keyB: 
     type: string 
    # If keyA and keyB are required: 
    required: 
     - keyA 
     - keyB 

Um anzugeben, dass die Anforderungsdaten JSON ist, verwenden die consumes Taste am Bedienebene. Wenn alle Ihre API-Vorgänge JSON verwenden, können Sie stattdessen auf der Stammebene der Spezifikation hinzufügen.