使用 Spring 可分页的 OpenAPI 生成器答案

【问题标题】：OpenAPI Generator Pageable with Spring使用 Spring 可分页的 OpenAPI 生成器
【发布时间】：2020-04-19 16:01:13
【问题描述】：

我希望 OpenAPI Generator (https://github.com/OpenAPITools/openapi-generator) 能够根据 Spring Boot Data 中的实现在 API 中生成 Pageable 参数。我一直在努力寻找合适的、开箱即用的解决方案，但找不到。

理想情况下，这个 Pageable 参数应该以下列方式仅添加到 GET 方法中：

default ResponseEntity<User> getUser(@ApiParam(value = "value",required=true) @PathVariable("id") Long id, **Pageable pageable**)

因此，在我的控制器中实现此接口后，我需要覆盖它并具有上述的 Pageable 参数。我不想有单独的大小或页面参数，这里只有这个 Pageable。

感谢任何提示和帮助！

【问题讨论】：

据我所知，如果不向 api 添加大小/页面，这是不可能的。为什么要隐藏它？没有它，没有人知道它正在分页......
@MartinHauner 我们希望在我们的 openAPI .yaml 文件中有 page,size,sort ，所以我们的其他团队知道分页存在，但是在我们生成的 API 作为后端，我们希望只有这个 Pageable 参数，因为 spring 将处理具有 page、size、sort 参数并将其转换为 Pageable 对象

标签： java spring code-generation openapi openapi-generator

【解决方案1】：

不幸的是，这不是最终的解决方案，但它已经完成了一半。或许还是有帮助的。

通过将可分页参数（大小、页面等）定义为对象查询参数，可以告诉生成器使用 Spring 对象，而不是从 api 生成 Pageable 类。这是通过导入映射完成的。

在毕业典礼中：

openApiGenerate {
    ....
    importMappings = [
        'Pageable': 'org.springframework.data.domain.Pageable'
    ]
}

告诉生成器使用 Spring 类而不是 api 中定义的类：

openapi: 3.0.2
info:
  title: Spring Page/Pageable API
  version: 1.0.0

paths:
  /page:
    get:
      parameters:
        - in: query 
          name: pageable
          required: false
          schema:
            $ref: '#/components/schemas/Pageable'
      responses:
        ...

components:
  schemas:
    Pageable: 
      description: minimal Pageable query parameters
      type: object
      properties:
        page:
          type: integer
        size:
          type: integer

映射的问题是生成器仍然添加@RequestParam() 注释并且再次破坏它。只有在未注释时才有效。

如果你有点冒险，你可以试试openapi-processor-spring（我是作者）。它确实处理了上面的示例。但它可能还有其他你不喜欢的限制。

【讨论】：

谢谢！我希望它比看起来更可配置，创建处理器的好主意，我仍然需要检查一下:)
“如果没有注释就可以工作”是什么意思？据我所知，openapi生成器插件也添加了注释。
在撰写本文时，（我不知道是否仍然如此）生成器在控制器方法的pageable 参数中添加了@RequestParam() 注释。这个混淆的 Spring 和 page& size 参数到 Pagable 对象的自动绑定不起作用。仅当Pagable 参数未使用@RequestParam 注释时才有效。
Kotlin-Spring v5.3.1 生成一个“pageable: Pageable?”没有@RequestParam 注释的参数。