Support annotation-based automatic grouping of APIs in Swagger UI

[mini0192]

Content & configuration

Swagger/OpenAPI definition:

plugins {
   id 'java'
   id 'org.springframework.boot' version '3.1.5'
   id 'io.spring.dependency-management' version '1.1.7'
}

group = 'org.example'
version = '1.0-SNAPSHOT'

repositories {
   mavenCentral()
}

dependencies {
   implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'
   implementation 'org.springframework.boot:spring-boot-starter-web'
   testImplementation platform('org.junit:junit-bom:5.10.0')
   testImplementation 'org.junit.jupiter:junit-jupiter'
   testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

test {
   useJUnitPlatform()
}

Swagger-UI configuration options:

SwaggerUI({
  // your config options here
})

?yourQueryStringConfig

Is your feature request related to a problem?

Yes. Currently, grouping APIs in Swagger UI requires manually creating GroupedOpenApi beans (in SpringDoc) or configuring repetitive Swagger metadata.
This is tedious and error-prone, especially in large projects with many controllers.
Developers often have to maintain multiple group definitions, which adds unnecessary boilerplate and potential for inconsistencies.

Describe the solution you'd like

Problem / Current Issues

Currently, grouping APIs in Swagger UI requires manually creating GroupedOpenApi beans for each group, for example:

@Bean
public GroupedOpenApi userApi() {
    return GroupedOpenApi.builder()
            .group("User API")
            .packagesToScan("mini.controller.user")
            .build();
}

@Bean
public GroupedOpenApi productApi() {
    return GroupedOpenApi.builder()
            .group("Product API")
            .packagesToScan("mini.controller.product")
            .build();
}

Adding annotation-based support for automatic grouping (e.g., @APIGroup) is expected to improve the developer experience by reducing boilerplate and making API organization more intuitive.

example.

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiGroup {
    String value();
    boolean auth() default false;
}

@ApiGroup("users")
@RestController
@RequestMapping("/users")
public class UserController { ... }

When this annotation is applied, Swagger UI should automatically create a group named "users" for all endpoints in that controller.

Describe alternatives you've considered

• Manually defining GroupedOpenApi beans for each group.
• Using package-based or path-based grouping.
  Both alternatives are repetitive and require extra maintenance whenever new controllers are added.

Additional context

• This feature would significantly improve developer productivity and maintainability.
• Could be implemented as a Spring Boot auto-configuration for SpringDoc/OpenAPI.
• Supports a cleaner, declarative way to organize API documentation without boilerplate.

[Mattias-Sehlstedt]

Is this type of declaration approach not possible anymore?

@Bean
public GroupedOpenApi publicApi() {
  return GroupedOpenApi.builder()
  .group("springshop-public")
  .pathsToMatch("/public/**")
  .build();
}
@Bean
public GroupedOpenApi adminApi() {
  return GroupedOpenApi.builder()
  .group("springshop-admin")
  .pathsToMatch("/admin/**")
  .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
  .build();
}

From here. To me it looks like the second example can utilize an annotation?

[mini0192]

Is this type of declaration approach not possible anymore?

@bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("springshop-public")
.pathsToMatch("/public/")
.build();
}
@bean
public GroupedOpenApi adminApi() {
return GroupedOpenApi.builder()
.group("springshop-admin")
.pathsToMatch("/admin/")
.addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
.build();
}
From here. To me it looks like the second example can utilize an annotation?

This method currently works for groups.
However, this method is path-dependent.
If you use /public/, you'll create a group with an endpoint of /public/.
However, if you change it to /api/public, you'll also need to modify that file.
Furthermore, if you create an endpoint that doesn't follow the rules, the problem becomes more complex.

//In this code, the annotation was used as ApiTag.
@Configuration
@SecurityScheme(
    name = "bearerAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT",
    in = SecuritySchemeIn.HEADER)
public class SwaggerConfig {

  @Bean
  public GroupedOpenApi adminApi() {
    return buildGroupedOpenApi("admin", MemberRole.ROLE_ADMIN);
  }

  @Bean
  public GroupedOpenApi userApi() {
    return buildGroupedOpenApi("user", MemberRole.ROLE_USER);
  }

  @Bean
  public GroupedOpenApi publicApi() {
    return buildGroupedOpenApi("public", MemberRole.ROLE_NONE);
  }

  private GroupedOpenApi buildGroupedOpenApi(String group, MemberRole role) {
    return GroupedOpenApi.builder()
        .group(group)
        .addOperationCustomizer(
            (operation, handlerMethod) -> {
              ApiTag apiTag =
                  Optional.ofNullable(handlerMethod.getMethodAnnotation(ApiTag.class))
                      .orElse(handlerMethod.getBeanType().getAnnotation(ApiTag.class));

              if (apiTag != null && apiTag.role() == role) {
                if (role == MemberRole.ROLE_ADMIN || role == MemberRole.ROLE_USER) {
                  operation.addSecurityItem(new SecurityRequirement().addList("bearerAuth"));
                }
                return operation;
              }
              return null;
            })
        .build();
  }
}

This is a part of the code I wrote. Currently, I'm handling the groups by hardcoding them.

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiGroup {
    String value();
    boolean auth() default false;
}

I think automating group creation using this annotation would improve the development experience.

[Mattias-Sehlstedt]

However, this method is path-dependent

But it does not have to be path dependent as per the example with addOpenApiMethodFilter? Or are we talking about the resource path or the path used to expose the specification?

However, if you change it to /api/public, you'll also need to modify that file.

If they are that closely related to each other, should we then not make them share a reference to a variable?
@RequestMapping(value = Controller.ROOT_PATH)

For the annotation suggestion, if the current controller package structure for the application is that each controller is tied to a specific group (I assume that since that is what the group tag would realize, unless the suggestion means that it should join groups that share the same name too, even if they are on different controllers), then I am not clearly understanding why a package scanning approach is prone to failing? The package structure is meant to replicate how they are exposed, is that then not enforced explicitly by that policy?

And if I am misunderstanding that, and different endpoints in different controllers should belong to different groups, doesn't

@Bean
public GroupedOpenApi adminApi() {
  return GroupedOpenApi.builder()
  .group("admin")
  .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
  .build();
}

solve that very well? Where the Admin.class is an interface annotation similar to your suggested ApiGroup, but you place it on each method for what group it should belong to?

[mini0192]

And if I am misunderstanding that, and different endpoints in different controllers should belong to different groups, doesn't

@bean
public GroupedOpenApi adminApi() {
return GroupedOpenApi.builder()
.group("admin")
.addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
.build();
}
solve that very well? Where the Admin.class is an interface annotation similar to your suggested ApiGroup, but you place it on each method for what group it should belong to?

To summarize what you said:

@Bean
public GroupedOpenApi adminApi() {
  return GroupedOpenApi.builder()
  .group("admin")
  .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
  .build();
}

I understand that this approach can achieve the functionality I want (please correct me if I’m wrong).

But what I actually want is to implement this feature without registering beans manually, using only annotations.
(I apologize if my previous explanation caused any confusion.)

Here’s my annotation:

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiGroup {
    String value();
}

And I want to be able to use it like this:

@ApiGroup("member")
@RequestMapping("/member")
@RestController
public class MemberController {
    @GetMapping("/test123")
    public String test() {
        return "test";
    }
}
//////////////////////////////
@ApiGroup("admin")
@RequestMapping("/admin")
@RestController
public class AdminController {
    @GetMapping("/test")
    public String test() {
        return "test";
    }
}

With this setup, I’d like the Swagger documentation to automatically create separate groups — one for member and one for admin.

Here’s the implementation I came up with:

@Configuration
@RequiredArgsConstructor
public class SwaggerConfig {

    private final ApplicationContext context;

    @Bean
    public List<GroupedOpenApi> apiGroups() {
        Map<String, Object> controllers = context.getBeansWithAnnotation(ApiGroup.class);
        List<GroupedOpenApi> groups = new ArrayList<>();
        for(Object controller : controllers.values()) {
            Class<?> targetClass = AopUtils.getTargetClass(controller);
            ApiGroup apiGroup = targetClass.getAnnotation(ApiGroup.class);
            groups.add(buildGroupedOpenApi(apiGroup.value()));
        }
        return groups;
    }

    private GroupedOpenApi buildGroupedOpenApi(String group) {
        return GroupedOpenApi.builder()
                .group(group)
                .addOpenApiMethodFilter(method -> checkGroup(method, group))
                .build();
    }

    private boolean checkGroup(Method method, String group) {
        if(method.isAnnotationPresent(ApiGroup.class)
                || method.getDeclaringClass().isAnnotationPresent(ApiGroup.class)) {
            ApiGroup apiGroup = method.getAnnotation(ApiGroup.class);
            if(apiGroup == null) apiGroup = method.getDeclaringClass().getAnnotation(ApiGroup.class);
            if(apiGroup == null) return false;
            return apiGroup.value().equals(group);
        }
        return false;
    }
}

(It’s a simplified version, so it might need optimization.)

By implementing it this way, we can group APIs in Swagger purely through annotations, without manually creating new beans. I think this would greatly improve the developer experience.