Java OpenApi 生成器使用对象作为查询参数

Question

我有以下控制器：

public interface GetScoreController {
  @GetMapping(value = "/score", produces = MediaType.APPLICATION_JSON_VALUE)
  @Operation(parameters = {@Parameter(in = ParameterIn.QUERY, name = "request")})
  Score getScore(ScoreRequest request);
}

而且我希望 OpenApi 在生成 Swagger 文档时将 ScoreRequest 中的所有属性显示为查询参数，因为这是请求是 POJO 时的结果：

我不知道 OpenApi 是否真的允许这样做，但如果我有太多请求参数，将它们收集在一个唯一的 POJO 中会更有用。

Answer 1

显然您正在尝试开发 RESTful 或基于 REST 的实现...在这种情况下，不建议您的 GET 端点在其中使用对象，仅 Path Params 或 Query Params.

将具有大量查询参数的 API 视为过滤器选项是很常见的。别怕。

但是，我认为你的方法 getScore 应该只接收 scoreId 作为路径参数（或者甚至是查询参数），作为 OOP 的最佳实践。

请参阅有关 Stack 的这篇文章，它非常关注 Rest 中的最佳实践 Api 设计： https://Whosebug.blog/2020/03/02/best-practices-for-rest-api-design/

Answer 2

向方法签名添加 @ParameterObject 注释。

Score getScore(@ParameterObject ScoreRequest request);
}

Java OpenApi 生成器使用对象作为查询参数

Java OpenApi generator use object as query parameter

java

spring

swagger

openapi

pojo