OpenAPITools/openapi-generator · error · RuntimeException

Value "{value}" for the generateSwaggerAnnotations parameter

Error message

Value "{value}" for the generateSwaggerAnnotations parameter is unsupported or misspelled

What it means

Validates the 'generateSwaggerAnnotations' additional property (OPT_GENERATE_SWAGGER_ANNOTATIONS) of the Micronaut Java generators. Accepted values are exactly: 'swagger1' (io.swagger:swagger-annotations), 'swagger2' (io.swagger.core.v3:swagger-annotations), 'true' (alias for swagger2), and 'false' (no annotations). The raw value is stringified with String.valueOf then matched case-sensitively; anything else throws a RuntimeException from processOpts.

Source

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

        } else if (testTool.equals(OPT_TEST_SPOCK)) {
            additionalProperties.put("isTestSpock", true);
        }

        if (additionalProperties.containsKey(OPT_GENERATE_SWAGGER_ANNOTATIONS)) {
            String value = String.valueOf(additionalProperties.get(OPT_GENERATE_SWAGGER_ANNOTATIONS));
            switch (value) {
                case OPT_GENERATE_SWAGGER_ANNOTATIONS_SWAGGER_1:
                    this.generateSwaggerAnnotations = OPT_GENERATE_SWAGGER_ANNOTATIONS_SWAGGER_1;
                    break;
                case OPT_GENERATE_SWAGGER_ANNOTATIONS_SWAGGER_2:
                case OPT_GENERATE_SWAGGER_ANNOTATIONS_TRUE:
                    this.generateSwaggerAnnotations = OPT_GENERATE_SWAGGER_ANNOTATIONS_SWAGGER_2;
                    break;
                case OPT_GENERATE_SWAGGER_ANNOTATIONS_FALSE:
                    this.generateSwaggerAnnotations = OPT_GENERATE_SWAGGER_ANNOTATIONS_FALSE;
                    break;
                default:
                    throw new RuntimeException("Value \"" + value + "\" for the " + OPT_GENERATE_SWAGGER_ANNOTATIONS + " parameter is unsupported or misspelled");
            }
        }
        if (OPT_GENERATE_SWAGGER_ANNOTATIONS_SWAGGER_1.equals(this.generateSwaggerAnnotations)) {
            additionalProperties.put("generateSwagger1Annotations", true);
        } else if (OPT_GENERATE_SWAGGER_ANNOTATIONS_SWAGGER_2.equals(this.generateSwaggerAnnotations)) {
            additionalProperties.put("generateSwagger2Annotations", true);
        }

        if (additionalProperties.containsKey(CodegenConstants.SERIALIZATION_LIBRARY)) {
            setSerializationLibrary((String) additionalProperties.get(CodegenConstants.SERIALIZATION_LIBRARY));
        }
        additionalProperties.put(this.serializationLibrary, true);
        this.jackson = JACKSON.equals(this.serializationLibrary);

        // Add all the supporting files
        String resourceFolder = projectFolder + "/resources";
        supportingFiles.add(new SupportingFile("common/configuration/application.yml.mustache", resourceFolder, "application.yml").doNotOverwrite());
        supportingFiles.add(new SupportingFile("common/configuration/logback.xml.mustache", resourceFolder, "logback.xml").doNotOverwrite());

View on GitHub (pinned to fcec517be3)

Solutions

Use exactly `swagger1`, `swagger2`, `true`, or `false` (all lowercase).
Remember `true` is equivalent to `swagger2`; use `false` to disable annotation generation.
If unsure, omit the option — the generator picks a default (false or swagger2 depending on client/server variant) and never throws when absent.

Example fix

# before
openapi-generator-cli generate -g java-micronaut -i api.yaml -p generateSwaggerAnnotations=TRUE
# after
openapi-generator-cli generate -g java-micronaut -i api.yaml -p generateSwaggerAnnotations=true

Defensive patterns

Strategy: validation

Validate before calling

# shell: validate the swagger annotations mode first
v="${SWAGGER_ANNOTATIONS:-}"
[ -z "$v" ] || case "$v" in
  swagger1|swagger2|true|false) ;;
  *) echo "generateSwaggerAnnotations must be swagger1|swagger2|true|false, got: $v" >&2; exit 2 ;;
esac

Type guard

private static final java.util.Set<String> SWAGGER_ANNOTATION_MODES =
        java.util.Set.of("swagger1", "swagger2", "true", "false");

boolean isValidSwaggerAnnotationsMode(String v) {
    return v == null || SWAGGER_ANNOTATION_MODES.contains(v);
}

Try / catch

try {
    new DefaultGenerator().opts(clientOptInput).generate();
} catch (RuntimeException e) {
    failBuild("generateSwaggerAnnotations value rejected: " + e.getMessage());
}

Prevention

Normalize the value to lowercase before passing it (tr "[:upper:]" "[:lower:]").
Prefer the explicit swagger1/swagger2 forms over true/false to make intent obvious.
Add a CI lint that greps config files for unlisted generateSwaggerAnnotations values.

When it happens

Trigger: -p generateSwaggerAnnotations=TRUE (uppercase), =1, =2, =yes, =none, =v2, =swagger (bare). Note a real boolean true/false passed programmatically works because String.valueOf(true) yields "true", but the uppercase string "TRUE" fails.

Common situations: Assuming the annotation version is picked with 1/2 or v1/v2; YAML config loaders that preserve 'TRUE' casing from hand-edited files; blog posts using long-form values like 'swagger-annotations'.

Related errors

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