Java Quarkus OpenAPI: How to order various paths/routes in a Quarkus resource?

[Aravinda93]

How can I add the sorting order for my API path endpoints using the Java OpenAPI annotations? I am currently using Quarkus to develop a rest-based application within that I am using the OpenAPI annotations to generate the Swagger-UI but I am not able to control the orders for various paths/routes that appear. Is there a way to achieve this by forcing the OpenAPI to always sort as per my need?

Following are multiple resources and endpoints I have:

ExtensionsResource:

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

    @POST
    @Path("/post/extensions")
    public String list() {
        return extension;
    }

    @GET
    @Path("/get/extension")
    public String list() {
        return extension;
    }

    @POST
    @Path("/post/extension")
    public String list() {
        return extension;
    }
}

I always want to ensure that the swagger-ui displays the API endpoints in the following order:

1. api/get/extension
2. api/post/extension
3. api/post/extensions

This above code is just for reference my actual code looks different I just want to know how to force the ordering of endpoints in Swagger-UI using the OpenAPI annotation.

The contents of my application.yaml file looks something like this:

quarkus:
  swagger-ui:
    always-include: true
    operations-sorter: "alpha"
  http:
    cors: true
    port: 9000

For operations-sorter: I would like to assign my custom order rather than alpha or any pre-defined order. Is there a way to achive this`

[quarkus-bot[bot]]

/cc @EricWittmann, @MikeEdgar, @phillip-kruger

[MikeEdgar]

@Aravinda93 - you may find issue #28509 helpful, let me know. You should be able to adapt the sorted lambda in the sample code comment [1] to work as needed.

[1] #28509 (comment)

[Aravinda93]

@MikeEdgar Thank you very much for the link. I was able to get it working by adding the functions in my public class SchemaExampleOASFilter implements OASFilter. I added the operationsId to my routes something like this:

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

    @Operation(operationId = "3")
    @POST
    @Path("/post/extensions")
    public String list() {
        return extension;
    }

    @Operation(operationId = "1")
    @GET
    @Path("/get/extension")
    public String list() {
        return extension;
    }
    
    @Operation(operationId = "2")
    @POST
    @Path("/post/extension")
    public String list() {
        return extension;
    }
}

Added the SchemaExampleOASFilter something like this:

public class SchemaExampleOASFilter implements OASFilter {

    @Override
    public void filterOpenAPI(OpenAPI openAPI) {

        //Method to sort various operations based on operationID to display in Swagger-UI
        final Map < String, PathItem > pathItems = openAPI.getPaths().getPathItems().entrySet().stream().sorted((o1, o2) - > {
            if (o1.getValue().getPOST() != null && o2.getValue().getPOST() != null) {
                int v1 = Integer.parseInt(o1.getValue().getPOST().getOperationId());
                int v2 = Integer.parseInt(o2.getValue().getPOST().getOperationId());
                return Integer.compare(v1, v2);
            }
            return 0;
        }).collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue, (v1, v2) - > v1, LinkedHashMap::new));

        //Add the sorted operations to Swagger-UI
        openAPI.getPaths().setPathItems(pathItems);

    }
}

And added it to my application.yml file something like this:

quarkus:
  swagger-ui:
    always-include: true
  http:
    cors: true
    port: 9000

mp:
  openapi:
    filter: "com.example.my.package.SchemaExampleOASFilter"

This made everything work for me and now, I am able to sort however I want.