Quarkus中如何通过OpenAPI注解控制Swagger-UI的API路径排序？

开发者阿泽

2026-8-10

解决Quarkus Swagger-UI自定义API端点排序问题

要实现你想要的自定义排序，需要结合OpenAPI的@Operation注解和修改Swagger-UI配置，具体步骤如下：

1. 修改Swagger-UI配置

在application.yaml中，把operationsSorter的值从"alpha"改为"order"，让Swagger-UI按照每个API操作指定的顺序值排序：

quarkus:
  swagger-ui:
    always-include: true
    tagsSorter: "alpha"
    operationsSorter: "order"  # 切换为按order值排序
  http:
    cors: true
    port: 9000

2. 给每个API方法添加@Operation注解并指定order值

在ExtensionResource类中，为每个接口方法导入并添加io.swagger.v3.oas.annotations.Operation注解，通过order属性设置排序优先级（数值越小，展示位置越靠前）：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.POST;
import jakarta.ws.rs.Path;

@Path("/api")
@Tag(
    name = "Extensions Controller",
    description = "Extensions Information")
public class ExtensionResource {

    @POST
    @Path("/post/extensions")
    @Operation(order = 3)  // 第三个展示
    public String listExtensions() {
        return "extensions";
    }

    @GET
    @Path("/get/extension")
    @Operation(order = 1)  // 第一个展示
    public String getExtension() {
        return "extension";
    }

    @POST
    @Path("/post/extension")
    @Operation(order = 2)  // 第二个展示
    public String addExtension() {
        return "extension";
    }
}