Swagger 引用一个 Spring 对象的响应，使用 Swagger 进行分页

Posted 2023-02-26

【中文标题】Swagger 引用一个 Spring 对象的响应，使用 Swagger 进行分页

【英文标题】：Swagger refer a response to a Spring object, paging with Swagger

【发布时间】：2019-10-28 23:02:53

【问题描述】：

在我的项目中，我使用 Swagger 模板生成所有控制器端点，我正在尝试实现一个返回 Spring 的 Page 对象而不是列表的端点。

这就是我所拥有的：

responses:
        200:
          schema:
            type: array
            items:
              $ref: '#/definitions/Metadata'

它会生成：

public ResponseEntity<List<Metadata>> getMetadataList()

但我希望 Swagger 使用 Spring 的 Page 而不是列表生成响应：

public ResponseEntity<Page<Metadata>> getMetadataList()

如何在 Swagger 模板中引用 Spring 的 Page 对象？我是否必须定义自己的 Page 对象，然后将 Spring 的 Page 映射到我的对象？

【参考方案1】：

附加生成的带有 Page 对象的 swagger api 文档。

swagger

responses:
        '200':
          description: OK
          schema:
           $ref: '#/definitions/Page%C2%ABMetadata%C2%BB'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
definitions:
  Metadata:
    type: object
    properties:
      data:
        type: string
    title: Metadata
  Pageable:
    type: object
    properties:
      offset:
        type: integer
        format: int64
      pageNumber:
        type: integer
        format: int32
      pageSize:
        type: integer
        format: int32
      paged:
        type: boolean
      sort:
        $ref: '#/definitions/Sort'
      unpaged:
        type: boolean
    title: Pageable
  Page«Metadata»:
    type: object
    properties:
      content:
        type: array
        items:
          $ref: '#/definitions/Metadata'
      empty:
        type: boolean
      first:
        type: boolean
      last:
        type: boolean
      number:
        type: integer
        format: int32
      numberOfElements:
        type: integer
        format: int32
      pageable:
        $ref: '#/definitions/Pageable'
      size:
        type: integer
        format: int32
      sort:
        $ref: '#/definitions/Sort'
      totalElements:
        type: integer
        format: int64
      totalPages:
        type: integer
        format: int32
    title: Page«Metadata»
  Sort:
    type: object
    properties:
      empty:
        type: boolean
      sorted:
        type: boolean
      unsorted:
        type: boolean
    title: Sort

【讨论】：

但是这是一个基于Spring的Page创建的对象，我仍然需要将Spring的Page映射到这个对象。是否有可能在 Swagger 中有这样的参考：#/definitions/org.springframework.data.domain.Page？有了这个解决方案，我需要为每个对象重新定义 Page> ?