spring - 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