How to describe list of particular objects using Swagger in Spring Boot?

Question

I described my controller using Swagger but when I tried to extract .yaml description of controller, as response of endpoints I found list of objects. How to make Swagger describe those list as list of particular objects such as list of cars, list of houses, list of animals, etc. and then to describe what particular object like car, house or animal is. My case is:

/dummy_endpoint:
get:
  tags:
    - foo-controller
  summary: Get foo list
  description: Send GET request to obtain foo list
  operationId: findAllFooUsingGET
  produces:
     - application/json
  responses:
    '200':
      description: Foo list obtained successfully
      schema:
        type: array
        items:
          type: object
    '401':
      description: Unauthorized
    '403':
      description: Forbidden
    '404':
      description: Not Found

What I want to get:

/dummy_endpoint:
  get:
    tags:
      - foo-controller
    summary: Get foo list
    description: Send GET request to obtain foo list
    operationId: findAllFooUsingGET
    produces:
      - application/json
    responses:
      '200':
        description: Foo list obtained successfully
        schema:
          type: array
          items:
            type: Foo
      '401':
        description: Unauthorized
      '403':
        description: Forbidden
      '404':
        description: Not Found
definitions:
  Foo:
    type: object
    properties:
      id:
        type: integer
        format: int32
      name:
        type: String

What version of swagger are you using?

M. Dudek
– M. Dudek

2021-12-17 12:29:54 +00:00
Commented Dec 17, 2021 at 12:29 — M. Dudek
– M. Dudek, Commented Dec 17, 2021 at 12:29
I'm using 2.0 version.

kole
– kole

2021-12-17 12:45:09 +00:00
Commented Dec 17, 2021 at 12:45 — kole
– kole, Commented Dec 17, 2021 at 12:45

M. Dudek · Accepted Answer · 2021-12-17 12:50:06Z

1

I assume OpenAPI version 2.0 (based on the syntax in example). If you're using 3.0, let me know.

What you are looking for is ref. Check-in Swagger specification in section Input and Output Models and here in section Array and Multi-Value Parameters about arrays.

For example:

...
responses:
  '200':
    description: Foo list obtained successfully
    schema:
      type: array
      items:
        $ref: "#/definitions/Foo"
...
definitions:
  Foo:
    type: object
    properties:
      ...

edited Dec 17, 2021 at 12:50

answered Dec 17, 2021 at 12:38

M. Dudek

1,08511 silver badges31 bronze badges

Sign up to request clarification or add additional context in comments.

3 Comments

kole Over a year ago

Is there way for automatically adding those ref params, for example through @ApiResponse annotation ?

M. Dudek Over a year ago

Are you talking about an API for Java?

M. Dudek Over a year ago

It's available, you have value schema in @ApiResponse annotation. Here is example (2nd with output for class User) in section Operation Annotations. For your case schema = @Schema(implementation = Foo.class).

kole · Accepted Answer · 2021-12-20 10:53:27Z

0

Thing that solved my problem was the usage of responseContainer property from @ResponseApi annotation, where I put type of response container like List, Array etc. and putting into response property type of objects that are stored into container.

answered Dec 20, 2021 at 10:53

kole

215 bronze badges

Collectives™ on Stack Overflow

How to describe list of particular objects using Swagger in Spring Boot?

2 Answers 2

3 Comments

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

3 Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Related