OpenAPITools/openapi-generator · error · IllegalArgumentException

swagger1AnnotationLibrary is not supported with Spring Boot

Error message

swagger1AnnotationLibrary is not supported with Spring Boot > 3.x

What it means

Thrown when annotationLibrary=swagger1 is combined with useSpringBoot3 or useSpringBoot4. Swagger 1.x annotations target javax.* packages and pre-Jakarta Spring, while Boot 3/4 generators switch templates to jakarta.* namespace. The generator rejects the combination up front instead of emitting sources that cannot compile.

Source

Thrown at modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java:663

        if (isUseSpringBoot4()) {
            setUseSpringBoot3(false);
        }
        if (isNotEmpty(clientRegistrationId)) {
            if (!SPRING_HTTP_INTERFACE.equals(library)) {
                throw new IllegalArgumentException(CLIENT_REGISTRATION_ID + " is only supported with the " + SPRING_HTTP_INTERFACE + " library");
            }
            if (!isUseSpringBoot4()) {
                throw new IllegalArgumentException(CLIENT_REGISTRATION_ID + " requires " + USE_SPRING_BOOT4 + "=true because @ClientRegistrationId is provided by Spring Security 7");
            }
        }
        if (useSpringSecurityPreAuthorize && !SPRING_BOOT.equals(library)) {
            throw new IllegalArgumentException(USE_SPRING_SECURITY_PRE_AUTHORIZE
                    + " is only supported with the " + SPRING_BOOT + " library");
        }

        if (isUseSpringBoot3() || isUseSpringBoot4()) {
            if (AnnotationLibrary.SWAGGER1.equals(getAnnotationLibrary())) {
                throw new IllegalArgumentException(AnnotationLibrary.SWAGGER1.getPropertyName() + " is not supported with Spring Boot > 3.x");
            }
            useJakartaEe = true;
            applyJakartaPackage();
        }
        if(isUseJackson3() && !isUseSpringBoot4()){
            throw new IllegalArgumentException("useJackson3 is only available with Spring Boot >= 4");
        }
        if(this.useJackson3){
            this.applyJackson3Package();
        } else {
            this.applyJackson2Package();
        }

        convertPropertyToStringAndWriteBack(RESOURCE_FOLDER, this::setResourceFolder);
        convertPropertyToBooleanAndWriteBack(USE_HTTP_SERVICE_PROXY_FACTORY_INTERFACES_CONFIGURATOR, this::setUseHttpServiceProxyFactoryInterfacesConfigurator);

        convertPropertyToBooleanAndWriteBack(ADDITIONAL_NOT_NULL_ANNOTATIONS, this::setAdditionalNotNullAnnotations);

View on GitHub (pinned to fcec517be3)

Solutions

1. Use annotationLibrary=springdoc (recommended for Boot 3/4) or swagger2 instead.
2. Only keep swagger1 if you genuinely target Spring Boot 2.x, i.e. remove useSpringBoot3/useSpringBoot4.

Example fix

# before
-DannotationLibrary=swagger1 -DuseSpringBoot3=true

# after
-DannotationLibrary=springdoc -DuseSpringBoot3=true

# bash
if { [ "$USE_SPRING_BOOT3" = "true" ] || [ "$USE_SPRING_BOOT4" = "true" ]; } \
   && [ "$ANNOTATION_LIBRARY" = "swagger1" ]; then
  echo "swagger1 annotations require Spring Boot 2.x" >&2; exit 1
fi

// Java
try {
    new DefaultGenerator().opts(input).generate();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("swagger1")) {
        // switch annotationLibrary to springdoc and re-run once with corrected config
    }
}

When it happens

Trigger: -g spring -DannotationLibrary=swagger1 with -DuseSpringBoot3=true or -DuseSpringBoot4=true.

Common situations: Upgrading a Boot 2 service to Boot 3/4 while keeping the old annotationLibrary setting; templates or docs that predate Springdoc; teams disabling springdoc for license reasons and falling back to swagger1 by habit.

Related errors

• Flags 'useSwaggerAnnotations' (v2) and 'useSwaggerV3Annotati
• This library currently only supports jackson serialization.
• The Annotation Library [%s] is not supported by this generat
• swagger1AnnotationLibrary is not supported with Spring Boot
• Currently, reactive option doesn't supported by Spring Cloud

AI-assisted analysis of OpenAPITools/openapi-generator@fcec517be3 (2026-08-22). Data as JSON: /api/errors/77eaa8cb16de8bdf. Report an issue: GitHub.