如何从含分页参数的OpenAPI定义生成仅带Pageable的Spring方法

要实现从包含page/size/sort参数的OpenAPI定义中，生成仅带Pageable pageable参数的Spring API接口，同时保证OpenAPI定义与实际API行为一致，有两种实用方案：

方案一：利用OpenAPI扩展参数快速实现 #

这是最简便的方式，无需修改模板，通过两个扩展参数配合即可：

1. 在OpenAPI YAML的page/size/sort查询参数上添加x-codegen-ignore: true，让生成器忽略这三个单独参数
2. 在对应的GET接口上添加x-spring-paginated: true，触发生成器生成Pageable参数

示例OpenAPI YAML片段：

paths:
  /snakes:
    get:
      summary: 获取所有蛇类数据
      operationId: findAll
      x-spring-paginated: true
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
          x-codegen-ignore: true
        - name: size
          in: query
          schema:
            type: integer
            minimum: 1
            default: 20
          x-codegen-ignore: true
        - name: sort
          in: query
          schema:
            type: array
            items:
              type: string
          x-codegen-ignore: true
      responses:
        '200':
          description: 成功返回蛇类列表
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Snake'

生成后的Java接口会自动变成：

@GetMapping("/snakes")
public ResponseEntity<List<Snake>> findAll(Pageable pageable);

同时OpenAPI定义中依然保留page/size/sort参数，与实际API的分页排序行为完全一致（Spring的Pageable会自动解析这三个查询参数）。

方案二：自定义生成器模板（适合复杂定制场景） #

如果需要更灵活的参数控制（比如同时保留其他自定义查询参数），可以修改OpenAPI Generator的Spring API模板：

1. 导出Spring生成器的默认模板（执行openapi-generator config-help -g spring可查看模板路径，或直接从官方仓库下载）
2. 修改api.mustache模板中的参数生成逻辑：
   • 过滤掉page/size/sort三个查询参数
   • 当接口标记了x-spring-paginated: true时，添加Pageable pageable参数

示例模板修改片段：

{{#parameters}}
  {{#isQueryParam}}
    {{#name}}
      {{#ne name "page"}}
        {{#ne name "size"}}
          {{#ne name "sort"}}
            {{>parameter}}
          {{/ne}}
        {{/ne}}
      {{/ne}}
    {{/name}}
  {{/isQueryParam}}
  {{^isQueryParam}}
    {{>parameter}}
  {{/isQueryParam}}
{{/parameters}}
{{#operation.x-spring-paginated}}
  Pageable pageable
{{/operation.x-spring-paginated}}

3. 生成代码时指定自定义模板路径：

openapi-generator generate -i openapi.yaml -g spring -t ./custom-templates

内容的提问来源于stack exchange，提问作者Mirza Prangon