How do I control tag order in Springdoc OpenAPI 3.0?

Question

I'm switching from Springfox 3.0 to OpenAPI 3.0 + Springdoc-openapi.
In Springfox the tag order is alphabetical, but in Springdoc's Swagger UI, the order appears to be random.

How do I control the Tag order on the UI? I'd prefer an ordering of my choosing, but would be OK with ordering alphabetically by tag name.

@Tag(name = MY_CONTROLLER_TAG_NAME, description = MY_CONTROLLER_TAG_DESC)
public class MyController {

Desired Order:

• Paginated Endpoints
• User Access
• Tagging
• Tagging - Admin
• User Management
• User Management - Admin

Actual Order:

• User Access
• Tagging
• Paginated Endpoints
• Tagging - Admin
• User Management - Admin
• User Management

POM Dependencies:

        <springdoc-openapi.version>1.6.4</springdoc-openapi.version>
...
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>${springdoc-openapi.version}</version>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-security</artifactId>
            <version>${springdoc-openapi.version}</version>
        </dependency>

Application.yml:

springdoc:
  show-actuator: ${SWAGGER_ENABLED:true}
  swagger-ui:
    doc-expansion: none
  api-docs:
    enabled: ${SWAGGER_ENABLED:true}
  model-converters:
    pageable-converter:
      enabled: true

Woodrum

Is there a way to achieve something similar using the Quarkus-based rest application? I tried to achieve something similar for my quarkus-based application but could not get anything. Please find my question here: https://mcmap.net/q/1325850/-java-quarkus-openapi-how-to-order-various-paths-in-a-quarkus-resource/7584240 – Gans

Answer 1

try either:

springdoc.swagger-ui.tagsSorter: alpha

springdoc.writer-with-order-by-keys: true

https://springdoc.org/properties.html

Windpipe

Answer 2

If you want to control the order programmatically, you can also try the following (rather crude, but effective) approach:

@Configuration
@OpenAPIDefinition
public class OpenApiConfiguration {

  @Bean
  public GroupedOpenApi.Builder myAPIBuilder() {
      return GroupedOpenApi.builder()
              .group("My Group")
              .addOpenApiCustomizer(openApi -> {

                  // change order of tags
                  Tag[] reordered = new Tag[10];
                  openApi.getTags().forEach(tg -> {
                      if(tg.getName().equalsIgnoreCase("Paginated Endpoints")) reordered[0] = tg;
                      if(tg.getName().equalsIgnoreCase("User Access")) reordered[1] = tg;
                      if(tg.getName().equalsIgnoreCase("Tagging")) reordered[2] = tg;
                      // and so on
                  });
                  openApi.tags(Arrays.asList(reordered));
              })
              .pathsToMatch("/api/**");
  }
} 

Lynettelynn

Answer 3

As mentioned in the Swagger documentation, setting a global tags section also controls the default sorting in Swagger UI. To do this, you just need to add the OpenAPIDefinition annotation and set the tags in the desired order. As this annotation can only be set once in your project, just create a class with it.

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.tags.Tag;

@OpenAPIDefinition(
tags = {
  @Tag(name = "tag1"),
  @Tag(name = "tag2"),
  @Tag(name = "tag3")
})

public class OpenApiConfig {}

Antonomasia