Ask a Question

schema of the responses when response parameters are repeated itself

SOLVED
Sibqo
Occasional Contributor

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

1 ACCEPTED SOLUTION

Accepted Solutions
HKosova
Moderator

Re: schema of the responses when response parameters are repeated itself

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.


Helen Kosova
SmartBear Documentation Team Lead
________________________
EVENT Participate in our annual online activities to have fun and be rewared:
Join Wintertainment 2021

View solution in original post

6 REPLIES 6
HKosova
Moderator

Re: schema of the responses when response parameters are repeated itself

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

Helen Kosova
SmartBear Documentation Team Lead
________________________
EVENT Participate in our annual online activities to have fun and be rewared:
Join Wintertainment 2021
Sibqo
Occasional Contributor

Re: schema of the responses when response parameters are repeated itself

@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
Moderator

Re: schema of the responses when response parameters are repeated itself

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.


Helen Kosova
SmartBear Documentation Team Lead
________________________
EVENT Participate in our annual online activities to have fun and be rewared:
Join Wintertainment 2021

View solution in original post

Sibqo
Occasional Contributor

Re: schema of the responses when response parameters are repeated itself

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?

HKosova
Moderator

Re: schema of the responses when response parameters are repeated itself

See my answers above. The first example is for OpenAPI 3.0, the second example is for OpenAPI 2.0.


Helen Kosova
SmartBear Documentation Team Lead
________________________
EVENT Participate in our annual online activities to have fun and be rewared:
Join Wintertainment 2021
Sibqo
Occasional Contributor

Re: schema of the responses when response parameters are repeated itself

Hi @HKosova  thankyou so much, now i got it... it worked.. Thanks again.

cancel
Showing results for 
Search instead for 
Did you mean: