OpenAPITools/openapi-generator · error · IllegalArgumentException

The [%s] documentation provider does not support [%s] as com

Error message

The [%s] documentation provider does not support [%s] as complementary annotation library

What it means

Each DocumentationProvider declares which annotation libraries it can be combined with: springdoc only pairs with swagger2, while none/source pair with any library (DocumentationProviderFeatures.java:64-78). Even when both individual values are supported by kotlin-spring, processOpts() rejects incompatible pairs with an IllegalArgumentException. This is a cross-option consistency check that runs after the two individual checks.

Source

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

                throw new IllegalArgumentException(msg);
            }

            annotationLibrary = AnnotationLibrary.ofCliOption(
                    (String) additionalProperties.getOrDefault(ANNOTATION_LIBRARY,
                            documentationProvider.getPreferredAnnotationLibrary().toCliOptValue())
            );

            if (!supportedAnnotationLibraries().contains(annotationLibrary)) {
                String msg = String.format(Locale.ROOT, "The Annotation Library [%s] is not supported by this generator",
                        annotationLibrary.toCliOptValue());
                throw new IllegalArgumentException(msg);
            }

            if (!documentationProvider.supportedAnnotationLibraries().contains(annotationLibrary)) {
                String msg = String.format(Locale.ROOT,
                        "The [%s] documentation provider does not support [%s] as complementary annotation library",
                        documentationProvider.toCliOptValue(), annotationLibrary.toCliOptValue());
                throw new IllegalArgumentException(msg);
            }

            additionalProperties.put(DOCUMENTATION_PROVIDER, documentationProvider.toCliOptValue());
            additionalProperties.put(documentationProvider.getPropertyName(), true);
            additionalProperties.put(ANNOTATION_LIBRARY, annotationLibrary.toCliOptValue());
            additionalProperties.put(annotationLibrary.getPropertyName(), true);
        } else {
            additionalProperties.put(DOCUMENTATION_PROVIDER, DocumentationProvider.NONE);
            additionalProperties.put(ANNOTATION_LIBRARY, AnnotationLibrary.NONE);
        }
        if (additionalProperties.containsKey(USE_SPRING_BOOT3)) {
            this.setUseSpringBoot3(convertPropertyToBoolean(USE_SPRING_BOOT3));
        }
        if (additionalProperties.containsKey(USE_SPRING_BOOT4)) {
            this.setUseSpringBoot4(convertPropertyToBoolean(USE_SPRING_BOOT4));
        }
        if (additionalProperties.containsKey(USE_SPRING_BUILT_IN_VALIDATION)) {
            this.setUseSpringBuiltInValidation(convertPropertyToBoolean(USE_SPRING_BUILT_IN_VALIDATION));

View on GitHub (pinned to fcec517be3)

Solutions

With `documentationProvider=springdoc`, use `annotationLibrary=swagger2` or simply omit annotationLibrary (it defaults to the provider's preferred library).
If you must keep swagger1 annotations, switch the provider: `documentationProvider=source` (or `none`), which supports all annotation libraries.
Audit the full option string for stale provider/annotation pairs after upgrading the generator.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

// mirror the provider->library pairing table before generating
Map<String, Set<String>> allowed = Map.of(
    "SPRINGDOC", Set.of("SWAGGER2"),
    "NONE",      Set.of("NONE", "SWAGGER1", "SWAGGER2"),
    "SOURCE",    Set.of("NONE", "SWAGGER1", "SWAGGER2"));
String dp = String.valueOf(opts.getOrDefault("documentationProvider", "SPRINGDOC")).toUpperCase(Locale.ROOT);
String al = String.valueOf(opts.getOrDefault("annotationLibrary", "SWAGGER2")).toUpperCase(Locale.ROOT);
if (!allowed.getOrDefault(dp, Set.of()).contains(al)) {
    throw new IllegalArgumentException(dp + " cannot be combined with " + al);
}

Try / catch

try {
    new DefaultGenerator().opts(clientOptInput).generate();
} catch (IllegalArgumentException e) {
    // message states the unsupported combination; surface it with the valid pairings
    throw new BuildException("Invalid kotlin-spring options: " + e.getMessage(), e);
}

Prevention

Set documentationProvider only, and let annotationLibrary default to its preferred value.
When changing providers, delete the old annotationLibrary flag instead of overwriting blindly.
Keep a tested, known-good option string per project and diff against it in code review.

When it happens

Trigger: Running `-g kotlin-spring` with `--additional-properties documentationProvider=springdoc,annotationLibrary=swagger1` (or annotationLibrary=none with springdoc). springdoc's supportedAnnotationLibraries() contains only SWAGGER2, so any other pairing with springdoc throws at KotlinSpringServerCodegen.java:548.

Common situations: Migrating a legacy swagger1-annotated kotlin-spring project to springdoc while keeping the old annotationLibrary flag; setting annotationLibrary explicitly because an example did so, without realizing springdoc implies swagger2; partially edited CI option lists.

Related errors

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