Springdoc-OpenAPI 带路径参数和命令 object

Question

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

我正在尝试使用 Springdoc 为 Spring 引导 controller 生成 OpenAPI 规范。 我有一个具有多个路径变量的路径的映射，并且方法签名接受命令 object（命令 object 是从这些路径变量自动构造的）。 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);
}

Answer 2

请注意，@Parameter 不会在带有 POST 的 UI 中显示。 因为 POST 中只有正文。 所以你应该使用@io.swagger.v3.oas.annotations.parameters.RequestBody(description="blabla") 和@org.springframework.web.bind.annotation.RequestBody