Forum Discussion

Sibqo's avatar
Sibqo
Occasional Contributor
3 years ago
Solved

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

  • 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.

6 Replies

  • HKosova's avatar
    HKosova
    SmartBear Alumni (Retired)

    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

      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)

        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.