OpenAPI & spring-doc 未在控制器中找到所有映射 class

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服务生成文档，其他路径被忽略。

我尝试过的：

最初两个 POST 方法都被命名为 post。为了避免冲突，我重命名了。
我没有设置控制器级路径。
检查注释导入
未命中文档的缓存版本

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

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

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

谢谢

编辑配置 class

@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

以上属性匹配 start 和 end 与 /v2、/v3、/status 的端点， /api/v1。这无法匹配 /users/v2/ 甚至 /v2/users 等形式的端点

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

考虑以下示例

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

OpenAPI & spring-doc 未在控制器中找到所有映射 class

OpenAPI & spring-doc not finding all mappings in a controller class

swagger

spring-boot

openapi

springdoc

springdoc-openapi-ui