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

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.

    • Sibqo's avatar
      Sibqo
      Occasional Contributor
      4 years ago

      ok here is for example the response of my API:

       

      [

      {

      "id":"fgh",

      "code":"edf"

      }

      {

      "id":"ert",

      "code":"aws"

      }]

      what will be yaml code for this response?