springdoc-openapi-ui + swagger 不理解 @PathVariable required = false 标志

Question

我使用这个库来生成文档：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.0</version>
</dependency>

我有这个控制器：

@RestController
public class TestController {

    @GetMapping("/test{hz}")
    public String test(@PathVariable(value = "hz", required = false) String hz) {
        return "test";
    }
}

但我得到这个文档：

为什么required = false不起作用？

我试过这个：

@RestController
public class TestController {

    @GetMapping("/test{hz}")
    public String test(
            @Parameter(description = "foo", required = false)
            @PathVariable(value = "hz", required = false) String hz) {
        return "test";
    }
}

也不起作用

编辑：（@Helen 评论的答案）-我当然知道这一点：

@RestController
public class TestController {

    @GetMapping(value = {"/test", "/test{hz}"})
    public String test(
            @Parameter(description = "foo", required = false)
            @PathVariable(value = "hz", required = false) String hz) {
        return "test";
    }
}

我尝试了这个：

@PathVariable(value = "hz", required = false) Optional<String> hz

它使文档变得更糟。所以我没有添加这段代码。它{"/test", "/test{hz}"}看起来像这样：

Answer 1

这符合 OpenAPI 规范。

当客户端进行 API 调用时，每个路径参数必须替换为实际值。在 OpenAPI 中，路径参数是使用 in:path 定义的。参数名称必须与路径中指定的名称相同。还记得添加required: true，因为路径参数始终是必需的。

你可以看一下文档：

• https://swagger.io/docs/specification/describing-parameters/#path-parameters