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);
}

Answer 2

请注意，@Parameter不显示在UI与POST。因为POST中只有主体。所以你可以任意使用@io.swagger.v3.oas.annotations.parameters.RequestBody(描述="blabla"和@org.springframework.web.bind.annotation.RequestBody