What causes "swagger1AnnotationLibrary is not supported with Spring Boot > 3.x" in OpenAPITools/openapi-generator?

Migrate annotations: use `annotationLibrary=swagger2` (springdoc's pairing) with Boot 3/4.

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

Swagger-Core 1.x annotations (swagger1) target the javax* namespace and predate Jakarta EE, so kotlin-spring refuses them when generating for Spring Boot 3 or 4. Inside the `isUseSpringBoot3() || isUseSpringBoot4()` block, processOpts() throws if the resolved annotation library is SWAGGER1 (KotlinSpringServerCodegen.java:861). This runs after the provider/library combination checks, so swagger1 itself is a supported library value for kotlin-spring — it is the Boot-version pairing that fails.

Source

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

            this.setUseEnumValueInterface(convertPropertyToBoolean(CodegenConstants.USE_ENUM_VALUE_INTERFACE));
        }
        writePropertyBack(CodegenConstants.USE_ENUM_VALUE_INTERFACE, useEnumValueInterface);
        if (isUseSpringBoot3() && isUseSpringBoot4()) {
            throw new IllegalArgumentException("Choose between Spring Boot 3 and Spring Boot 4");
        }

        if (isUseJackson3() && !isUseSpringBoot4()) {
            throw new IllegalArgumentException("useJackson3 is only available with Spring Boot >= 4");
        }

        if (additionalProperties.containsKey(CodegenConstants.OPENAPI_NULLABLE)) {
            this.setOpenApiNullable(convertPropertyToBoolean(CodegenConstants.OPENAPI_NULLABLE));
        }
        writePropertyBack(CodegenConstants.OPENAPI_NULLABLE, openApiNullable);

        if (isUseSpringBoot3() || isUseSpringBoot4()) {
            if (AnnotationLibrary.SWAGGER1.equals(getAnnotationLibrary())) {
                throw new IllegalArgumentException(AnnotationLibrary.SWAGGER1.getPropertyName() + " is not supported with Spring Boot > 3.x");
            }
            useJakartaEe = true;
            additionalProperties.put(USE_JAKARTA_EE, useJakartaEe);
            applyJakartaPackage();
        }
        writePropertyBack(USE_SPRING_BOOT3, isUseSpringBoot3());
        writePropertyBack(USE_SPRING_BOOT4, isUseSpringBoot4());

        modelTemplateFiles.put("model.mustache", ".kt");

        if (!this.interfaceOnly && this.delegatePattern) {
            apiTemplateFiles.put("apiInterface.mustache", ".kt");
            apiTemplateFiles.put("apiController.mustache", "Controller.kt");
        } else if (interfaceOnly) {
            apiTemplateFiles.put("apiInterface.mustache", ".kt");
        } else {
            apiTemplateFiles.put("api.mustache", "Controller.kt");
            apiTestTemplateFiles.put("api_test.mustache", ".kt");

View on GitHub (pinned to fcec517be3)

Solutions

Migrate annotations: use `annotationLibrary=swagger2` (springdoc's pairing) with Boot 3/4.
Or drop the Boot 3/4 flags to generate Boot 2.x-era output with swagger1 (only as a temporary measure).
Search the generated sources for io.swagger.annotations imports after switching, and update hand-written code referencing them.

Example fix

# before
openapi-generator-cli generate -g kotlin-spring -i api.yaml \
  --additional-properties useSpringBoot3=true,documentationProvider=source,annotationLibrary=swagger1
# after
openapi-generator-cli generate -g kotlin-spring -i api.yaml \
  --additional-properties useSpringBoot3=true,documentationProvider=source,annotationLibrary=swagger2

Defensive patterns

Strategy: validation

Validate before calling

boolean boot3plus = Boolean.parseBoolean(String.valueOf(opts.getOrDefault("useSpringBoot3", "false")))
        || Boolean.parseBoolean(String.valueOf(opts.getOrDefault("useSpringBoot4", "false")));
String al = String.valueOf(opts.getOrDefault("annotationLibrary", "SWAGGER2")).toUpperCase(Locale.ROOT);
if (boot3plus && "SWAGGER1".equals(al)) {
    throw new IllegalArgumentException("swagger1 annotations require Spring Boot <= 2.x output");
}

Try / catch

try {
    new DefaultGenerator().opts(clientOptInput).generate();
} catch (IllegalArgumentException e) {
    throw new BuildException("Invalid kotlin-spring options: " + e.getMessage(), e);
}

Prevention

Plan a swagger1 → swagger2 annotation migration before upgrading generated code past Boot 3.
After regenerating, grep sources for io.swagger.annotations imports to catch leftovers.
Keep annotation library choice consistent with the Jakarta EE switch the Boot version implies.

When it happens

Trigger: Running with `--additional-properties useSpringBoot3=true,annotationLibrary=swagger1` (or useSpringBoot4=true with swagger1). The provider must be compatible with swagger1 too (e.g. documentationProvider=source or none), otherwise error 163 fires first.

Common situations: Long-lived kotlin-spring projects with swagger1 annotations being upgraded to Boot 3/4 while keeping the legacy annotation library; mixed option sets assembled from old wiki pages plus new Boot 3 flags.

Related errors

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