How to PUT a JSON array of objects in Swagger?

Question

Currently using Swagger.io to document my API. Trying to understand how to document sending a custom json object.

PUT on a collection to /some_endpoint
MIME: application/json

Custom Data:

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

Is it possible to document this in Swagger?

/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

Are keyA and keyB fixed property names or is that a map with arbitrary key names? — Helen
– Helen, Commented Dec 22, 2016 at 21:22

Helen · Accepted Answer · 2016-12-23 08:15:04Z

JSON data is sent in the request body, so it needs to be defined as a body parameter. The body structure is described using the schema keyword (not type). In your example the data is an array of objects, where each object has properties keyA and keyB.

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

To specify that the request data is JSON, use the consumes key at the operation level. If all of your API operations consume JSON, you can add consumes at the root level of the spec instead.

Collectives™ on Stack Overflow

How to PUT a JSON array of objects in Swagger?

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related