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

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

CodePudding user response：

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

CodePudding user response：

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.