带有路径参数和命令对象的 Springdoc-OpenAPI

Question

我在 Springdoc 生成的 OpenAPI 规范中遇到验证错误，并且无法在网上找到与我的 Java 代码的形成方式相匹配的示例。

我正在尝试使用 Springdoc 为 Spring Boot 控制器生成 OpenAPI 规范。我有一个具有多个路径变量的路径的映射，并且方法签名接受命令对象（命令对象是从这些路径变量自动构造的）。Swagger-UI.html 似乎或多或少可以工作，但生成的 JSON/YAML 规范似乎无效。

我指的代码片段：

@GetMapping("/myPath/{foo}/{bar}/{baz}")
public Mono<MyServiceResponse> doSomethingInteresting(@Valid DoSomethingInterestingCommand command) {
    return interestingService.doSomethingInteresting(command);
}

生成的 OpenApi 片段是：

paths:
  '/myPath/{foo}/{bar}/{baz}':
    get:
      tags:
        - my-controller
      operationId: doSomethingInteresting
      parameters:
        - name: command
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/DoSomethingInterestingCommand'

这会产生如下错误：

Semantic error at paths./myPath/{foo}/{bar}/{baz}
Declared path parameter "foo" needs to be defined as a path parameter at either the path or operation level

为了使生成的规范格式良好，我应该采取哪些不同的做法？我也很好奇为什么 swagger-ui.html 页面似乎工作正常，但这并不那么重要。

Answer 1

要生成正确的 openAPI 规范，您可以添加 swagger-annotations。

@Parameter(in = ParameterIn.PATH, name ="foo" ,schema = @Schema(type = "string"))
@Parameter(in = ParameterIn.PATH, name ="bar" ,schema = @Schema(type = "string"))
@Parameter(in = ParameterIn.PATH, name ="baz" ,schema = @Schema(type = "string"))
@GetMapping("/myPath/{foo}/{bar}/{baz}")
public Mono<MyServiceResponse> doSomethingInteresting(@Valid @Parameter(hidden = true) DoSomethingInterestingCommand command) {
    return interestingService.doSomethingInteresting(command);
}