如何在OpenAPI 3的Swagger YAML中配置分页以生成正确Java接口方法？

一、先给 Swagger YAML 补上分页参数配置 #

要生成带分页的接口，首先得在接口定义里添加分页相关的查询参数，推荐把分页参数抽成可复用的组件：

1. 完善组件参数定义 #

components:
  parameters:
    GameIds:
      in: query
      schema:
        type: array
        items:
          type: integer
          format: int64
      name: gameIds
      description: >
        The Game Ids.
    # 新增分页参数组件
    Page:
      in: query
      description: 页码（从0开始）
      required: false
      schema:
        type: integer
        format: int32
        default: 0
    Size:
      in: query
      description: 每页条数
      required: false
      schema:
        type: integer
        format: int32
        default: 20
    Sort:
      in: query
      description: 排序规则，格式为：字段名,(asc|desc)，支持多字段排序
      required: false
      schema:
        type: array
        items:
          type: string

2. 在 tournament 接口中引用分页参数 #

同时要修改200响应的schema，明确返回分页结构（包含数据列表和分页元数据）：

/tournaments:
get:
  summary: 获取锦标赛列表（分页）
  operationId: listTournaments
  tags:
    - tournaments
  responses:
    '200':
      description: 分页的锦标赛列表
      content:
        application/json:
          schema:
            type: object
            properties:
              content:
                $ref: "#/components/schemas/tournaments"
              page:
                type: integer
                format: int32
              size:
                type: integer
                format: int32
              totalElements:
                type: integer
                format: int64
    default:
      description: 意外错误
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  parameters:
    - $ref: '#/components/parameters/GameIds'
    # 引用分页参数
    - $ref: '#/components/parameters/Page'
    - $ref: '#/components/parameters/Size'
    - $ref: '#/components/parameters/Sort'

二、Gradle 必须添加对应的配置项 #

要让生成的控制器方法自动把分页参数封装成Pageable对象并加上@ParameterObject注解，需要在configOptions里新增配置：

configOptions = [
        configPackage       : "com.tournaments.api.engine.config",
        java8               : "true",
        dateLibrary         : "java17",
        serializationLibrary: "jackson",
        library             : "spring-boot",
        useBeanValidation   : "true",
        interfaceOnly       : "true",
        serializableModel   : "true",
        useTags             : "true",
        additionalModelTypeAnnotations: "@lombok.Builder;@lombok.NoArgsConstructor;@lombok.AllArgsConstructor",
        // 关键配置：开启Spring Boot参数对象注解生成
        useSpringBootParameterObject: "true"
]

注：如果使用的是 OpenAPI Generator v6 以下版本，可能需要把配置项改成useParameterObject: "true"，但针对Spring Boot场景，优先用useSpringBootParameterObject。

三、生成后的代码效果 #

重新执行代码生成后，控制器接口会变成类似这样：

@GetMapping("/tournaments")
default ResponseEntity<PagedTournaments> listTournaments(
    @Parameter(name = "gameIds") @RequestParam(value = "gameIds", required = false) List<Long> gameIds,
    @ParameterObject Pageable pageable
) {
    // 业务逻辑实现
}

其中PagedTournaments就是对应Swagger中定义的分页响应DTO。

内容的提问来源于stack exchange，提问作者Alessandro Morsiani