是否可以配置 spring-openapi 以在 v3 api-docs 中生成可预测的顺序 output？

Question

在为 springdoc OpenAPI v3 api-docs 生成 output 时，任何细微的更改都会导致在生成的 v3 api 文档中产生完全不同的顺序。

保持此顺序可预测会很方便，特别是在使用.yaml output 时进行调试。因此，如果有人知道订购此顺序的方法，我将不胜感激。

Answer 1

springdoc-openapi 基于 io.swagger.v3.oas.models.OpenAPI 对象。

Paths 元素是 LinkedHashMap 类型，使用此类型时会保留顺序。 如果您使用@Parameters注释或@Operation注释以特定顺序声明所有参数，则将保留该顺序。

您在 swagger-ui 方面也有一些属性。 例如：

springdoc.swagger-ui.operationsSorter=method
springdoc.swagger-ui.tagsSorter=alpha

对于调试/测试/比较结果，您可以使用 JSONAssert 库进行比较。

最后，您可以使用 OpenAPICustomiser 对 OpenAPI object 的所有元素进行排序。

Answer 2

以下示例显示了如何使用 OpenAPICustomiser 完全控制路径排序。

@Configuration
public class OpenApiConfiguration {

    private static final List<String> PATHS_ORDER = List.of(
        "/api/test2",
        "/api/test3",
        "/api/test1"
    );

    @Bean
    public OpenApiCustomiser sortPaths() {
        return openApi -> {
            Paths paths = openApi
                .getPaths()
                .entrySet()
                .stream()
                .sorted(Comparator.comparing(entry -> PATHS_ORDER.contains(entry.getKey()) ? PATHS_ORDER.indexOf(entry.getKey()) : Integer.MAX_VALUE))
                .collect(Paths::new, (map, item) -> map.addPathItem(item.getKey(), item.getValue()), Paths::putAll);

            openApi.setPaths(paths);
        };
    }

}

（任何更好的选择将不胜感激）