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

Question

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

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

我有这个 Controller :

@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 规范。

Each path parameter must be substituted with an actual value when the client makes an API call. In OpenAPI, a path parameter is defined using in: path. The parameter name must be the same as specified in the path. Also remember to add required: true, because path parameters are always required.

你可以看看文档:

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