OpenAPI 和 spring-doc 没有在控制器类中找到所有映射

Question

这有点奇怪。 springdoc-openapi-ui v1.2.32，生成的文档只包含控制器内的少数映射。

例子：

    @Operation(
            summary = "Foo",
            description = "Foo"
    )
    @PostMapping(path="/v1/foo")
    public ResponseEntity<ResponseObject> postFoo(@RequestBody FooRequestObject searchRequest, HttpServletRequest request){ ... }


    @Operation(
            summary = "Bar",
            description = "Bar"
    )
    @GetMapping(path="/v1")
    public ResponseEntity<ResponseObject> getBar(@RequestBody BarRequestObject request, HttpServletRequest request){ ... }


    @Operation(
            summary = "Bar",
            description = "Bar"
    )
    @PostMapping(path="/v1")
    public ResponseEntity<ResponseObject> postBar(@RequestBody BarRequestObject request, HttpServletRequest request){ ... }

仅为postBar 和getBar 服务生成文档，忽略其他路径。

我尝试过的：

1. 最初两种 POST 方法都命名为 post。我重命名以避免冲突。
2. 我没有设置控制器级路径。
3. 检查注释导入
4. 未命中文档的缓存版本

如果我向控制器添加另一个服务（带有或不带有注释标记），它也不会显示在生成的 Swagger 中。例如：

@GetMapping(path="/test")
public String getTest(){
    return "test";
}

如果我将此方法添加到全新的控制器，则会生成 doc。

谢谢

编辑 配置类

@Configuration
public class SwaggerConfig {                                    

    @Bean
    public OpenAPI springOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("My API")
                .description("My API service documentation. ")
                .version("v1.0")
                .license(new License().name("Terms of Use").url("https://myapi.com/terms.html")));
    }
    
}

Answer 1

您面临的问题是由于您使用了paths-to-match 的级别 1 引用，这导致 Springdoc 过滤指定路径上仅可用的端点。

springdoc.paths-to-match=/api/v1,/v2,/v3,/status

上述属性匹配开始和结束为/v2、/v3、/status、/api/v1 的端点。这无法匹配可能是 /users/v2/ 甚至 /v2/users 等形式的端点。

虽然不支持完整的正则表达式来指定您想要包含的端点，但对 ** 的基本支持可以帮助您指定您想要包含/排除的级别。

考虑以下示例

springdoc.paths-to-match=/**/v1/**/

它将包括任何包含/v1/ 的端点。例如/users/v1/、/v1/dasboard 和/user/v1/dashboard。

springdoc.paths-to-match=/v2/**

它将仅匹配以 /v2 开头并进入 n 级深度的端点。 /v2/dashboard 等示例将被包括在内，但 /users/v2/something 将被排除在外。

springdoc.paths-to-match=/**/v1

它只会匹配以/v1 结尾的路径。像/users/v1 这样的例子会被匹配，而像/v1/user 这样的例子不会被匹配。

或者，您也可以更新您的Bean 以执行相同的操作。但请注意，属性文件优先于 bean 配置。

// you existing bean here

// Define an API group that'll include specific version. Can be helpful in versioning the APIs.
@Bean
public GroupedOpenApi hideApis() {
    return GroupedOpenApi.builder().group("default")
            .pathsToExclude("/api/v2/**", "/v2/**", "/**/v3/**")
            .pathsToMatch("/v1/**", "/api/v1/**")
            .build();
}