如何基于REST动词自定义排序SpringDoc OpenAPI的REST API？

一、编程方式（修改OpenAPI模型） #

这种方式直接修改后端生成的OpenAPI规范文档，无论使用哪种UI展示，接口顺序都会符合自定义规则。

创建一个OpenApiCustomizer Bean，遍历所有路径下的接口操作，按照指定的HTTP方法顺序重新排序：

import org.springdoc.core.customizers.OpenApiCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.PathItem;
import io.swagger.v3.oas.models.Operation;
import java.util.Arrays;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

@Configuration
public class OpenApiSortConfig {

    // 定义自定义的HTTP方法优先级顺序
    private static final List<String> HTTP_METHOD_PRIORITY = Arrays.asList("GET", "POST", "PATCH", "DELETE");

    @Bean
    public OpenApiCustomizer operationSortCustomizer() {
        return openApi -> {
            openApi.getPaths().values().forEach(pathItem -> {
                // 提取当前路径下的所有有效操作
                List<Map.Entry<String, Operation>> sortedOperations = pathItem.readOperationsMap().entrySet().stream()
                        .filter(entry -> entry.getValue() != null)
                        .sorted((entry1, entry2) -> {
                            // 获取方法在优先级列表中的索引，不在列表中的排最后
                            int index1 = HTTP_METHOD_PRIORITY.indexOf(entry1.getKey());
                            int index2 = HTTP_METHOD_PRIORITY.indexOf(entry2.getKey());
                            index1 = index1 == -1 ? HTTP_METHOD_PRIORITY.size() : index1;
                            index2 = index2 == -1 ? HTTP_METHOD_PRIORITY.size() : index2;
                            return Integer.compare(index1, index2);
                        })
                        .collect(Collectors.toList());

                // 清空原操作，按排序后的顺序重新设置
                pathItem.getOperations().clear();
                sortedOperations.forEach(entry -> {
                    switch (entry.getKey()) {
                        case "GET" -> pathItem.setGet(entry.getValue());
                        case "POST" -> pathItem.setPost(entry.getValue());
                        case "PATCH" -> pathItem.setPatch(entry.getValue());
                        case "DELETE" -> pathItem.setDelete(entry.getValue());
                        case "PUT" -> pathItem.setPut(entry.getValue());
                        case "HEAD" -> pathItem.setHead(entry.getValue());
                        case "OPTIONS" -> pathItem.setOptions(entry.getValue());
                        case "TRACE" -> pathItem.setTrace(entry.getValue());
                    }
                });
            });
        };
    }
}

二、YAML配置+自定义前端脚本（仅修改Swagger UI展示顺序） #

如果只需要在Swagger UI中按自定义顺序展示接口，无需修改OpenAPI规范，可以通过配置自定义JS脚本实现：

1. 在application.yml中添加Swagger UI自定义JS配置：

springdoc:
  swagger-ui:
    custom-js: /custom-swagger-sort.js

2. 在src/main/resources/static目录下创建custom-swagger-sort.js文件，内容如下：

window.addEventListener('load', function() {
    // 自定义HTTP方法的展示顺序（小写）
    const methodOrder = ['get', 'post', 'patch', 'delete', 'put', 'head', 'options', 'trace'];

    // 覆盖Swagger UI的操作排序逻辑
    SwaggerUIBundle.fn.operationsSorter = function(a, b) {
        const methodA = a.get('method');
        const methodB = b.get('method');
        const indexA = methodOrder.indexOf(methodA);
        const indexB = methodOrder.indexOf(methodB);
        // 不在列表中的方法排到最后
        return (indexA === -1 ? methodOrder.length : indexA) - (indexB === -1 ? methodOrder.length : indexB);
    };
});

启动应用后，Swagger UI中每个路径下的接口会按照GET → POST → PATCH → DELETE的顺序展示。

内容的提问来源于stack exchange，提问作者Mostafa Hassan