Forum Discussion

Sibqo's avatar
Sibqo
Occasional Contributor
4 years ago

schema of the responses when response parameters are repeated itself

Hi!

i want to ask about the responses like: If the api returns the list of all the users then in the response there is a list of users and each user having the same parameters like this:

[
{
"id": 1,
"code": "2y1"
},
{
"id": 2,
"code": "2y1"
}
]
 

then in the schema of this response how i can write in the yaml?

i had wriiten it as:

getallUsers:

   properties:

      properties:
         id:
            type: integer
        code:
            type: string

 

if i make the objects and arrays then it shows the error of duplicated key etc. If anyone have any idea kindly guide me

  • HKosova's avatar
    HKosova
    4 years ago

    If you mean array examples with multiple items, that's supported in OpenAPI 2.0 too. The "example" keyword needs to be alongside "type: array", like so:

          responses:
        '200':
          description: A list of users
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
            example:   # <--- on the same level as "type: array"
              - id: 1
                code: 2y1
              - id: 2
                code: 2y1

     

    If you mean multiple different examples for the same response or parameter, that's only supported in OpenAPI 3.0.

  • HKosova's avatar
    HKosova
    SmartBear Alumni (Retired)
    4 years ago

    Hi Sibqo,

     

    A response containing an array of objects can be described as follows:

    openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0

paths:
  /users:
    get:
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        code:
          type: string

     

    The auto-generated example in Swagger UI shows just one object by default. If you want to have multiple objects in the example value, you can add a response example like so:

          responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

              example:    # <--- Response example with two objects in an array
                - id: 1
                  code: 2y1
                - id: 2
                  code: 2y1
    • Sibqo's avatar
      Sibqo
      Occasional Contributor
      4 years ago

      HKosovaThank you so much for your time and guide. One thing i want to clear is that multiple examples are only allowed in open Api v3.0 or it is also allowed in swagger 2.0?

      • HKosova's avatar
        HKosova
        SmartBear Alumni (Retired)
        4 years ago

        If you mean array examples with multiple items, that's supported in OpenAPI 2.0 too. The "example" keyword needs to be alongside "type: array", like so:

              responses:
        '200':
          description: A list of users
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
            example:   # <--- on the same level as "type: array"
              - id: 1
                code: 2y1
              - id: 2
                code: 2y1

         

        If you mean multiple different examples for the same response or parameter, that's only supported in OpenAPI 3.0.