javaswaggerswagger-uiopenapiquarkus

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


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 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.

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

quarkus:
  swagger-ui:
    always-include: true
    tagsSorter: "alpha"
    operationsSorter: "alpha"
  http:
    cors: true
    port: 9000

Solution

  • 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.