{"record":{"id":"c6804d5813b594b6","repo":"OpenAPITools/openapi-generator","slug":"flags-useswaggerannotations-v2-and-useswagger","errorCode":null,"errorMessage":"Flags 'useSwaggerAnnotations' (v2) and 'useSwaggerV3Annotations' (v3) are mutually exclusive. Please enable only one.","messagePattern":"Flags 'useSwaggerAnnotations' \\(v2\\) and 'useSwaggerV3Annotations' \\(v3\\) are mutually exclusive\\. Please enable only one\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaJAXRSSpecServerCodegen.java","lineNumber":198,"sourceCode":"        convertPropertyToBooleanAndWriteBack(SUPPORT_ASYNC, this::setSupportAsync);\n        if (QUARKUS_LIBRARY.equals(library) || THORNTAIL_LIBRARY.equals(library) || HELIDON_LIBRARY.equals(library) || OPEN_LIBERTY_LIBRARY.equals(library) || KUMULUZEE_LIBRARY.equals(library)) {\n            // disable Swagger v2 annotations in library modes; MicroProfile or Swagger v3 may be used instead\n            useSwaggerAnnotations = false;\n        } else {\n            convertPropertyToBooleanAndWriteBack(USE_SWAGGER_ANNOTATIONS, value -> useSwaggerAnnotations = value);\n        }\n        // Swagger v3 can be used regardless of library\n        convertPropertyToBooleanAndWriteBack(USE_SWAGGER_V3_ANNOTATIONS, value -> useSwaggerV3Annotations = value);\n        // prefer v3 when requested\n        if (useSwaggerV3Annotations) {\n            useSwaggerAnnotations = false;\n        }\n        if (KUMULUZEE_LIBRARY.equals(library)) {\n            super.setSourceFolder(\"src/main/java\");\n        }\n\n        if (useSwaggerAnnotations && useSwaggerV3Annotations) {\n            throw new IllegalArgumentException(\"Flags 'useSwaggerAnnotations' (v2) and 'useSwaggerV3Annotations' (v3) are mutually exclusive. Please enable only one.\");\n        }\n        if (useSwaggerV3Annotations && useMicroProfileOpenAPIAnnotations) {\n            throw new IllegalArgumentException(\"Flags 'useSwaggerV3Annotations' and 'useMicroProfileOpenAPIAnnotations' are mutually exclusive. Please enable only one.\");\n        }\n\n        if (QUARKUS_LIBRARY.equals(library)) {\n            convertPropertyToBooleanAndWriteBack(USE_MICROPROFILE_OPENAPI_ANNOTATIONS, value -> useMicroProfileOpenAPIAnnotations = value);\n        }\n\n        if (QUARKUS_LIBRARY.equals(library)) {\n            convertPropertyToBooleanAndWriteBack(USE_MUTINY, value -> useMutiny = value);\n        }\n\n        convertPropertyToBooleanAndWriteBack(GENERATE_JSON_CREATOR, this::setGenerateJsonCreator);\n        convertPropertyToBooleanAndWriteBack(USE_ENUM_CASE_INSENSITIVE, this::setUseEnumCaseInsensitive);\n        convertPropertyToBooleanAndWriteBack(USE_SEALED, this::setUseSealed);\n\n        if (additionalProperties.containsKey(OPEN_API_SPEC_FILE_LOCATION)) {","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/OpenAPITools/openapi-generator/blob/fcec517be3cf5b7964296bcba25fbc97541484e7/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaJAXRSSpecServerCodegen.java#L180-L216","documentation":"Thrown by JavaJAXRSSpecServerCodegen.processOpts when useSwaggerAnnotations (io.swagger v2 annotations) and useSwaggerV3Annotations (io.swagger.core.v3) are both true — the templates cannot emit both annotation sets. Note the code force-disables useSwaggerAnnotations when v3 is requested ('prefer v3'), so in the standard config-driven flow this guard is nearly unreachable; it exists to protect programmatic setter sequences and future option paths.","triggerScenarios":"Passing --additional-properties useSwaggerAnnotations=true,useSwaggerV3Annotations=true to -g jaxrs-jersey (the JAX-RS spec generator). Programmatically setting both fields to true via setters after processOpts ordering differs. The CLI path alone normally cannot trip it because v3 wins first.","commonSituations":"Upgrades from Swagger 2 to OpenAPI 3 where teams enable the new flag but forget to remove the old one. Config management tools that merge option maps (base + override) can resurrect both flags even if the base config only meant one.","solutions":["Enable only one: keep useSwaggerV3Annotations=true and remove useSwaggerAnnotations (v3 is auto-preferred anyway)","Audit merged config sources (CLI + --config file + configOptions) for both keys being set","If you still target Swagger 2 tooling (springfox-era), keep useSwaggerAnnotations=true and drop the v3 flag","In embedded usage, set the flags through additionalProperties rather than direct field/setter calls so the v3-preference logic runs"],"exampleFix":"# before\nopenapi-generator-cli generate -g jaxrs-jersey -i api.yaml \\\n  --additional-properties useSwaggerAnnotations=true,useSwaggerV3Annotations=true\n\n# after\nopenapi-generator-cli generate -g jaxrs-jersey -i api.yaml \\\n  --additional-properties useSwaggerV3Annotations=true","handlingStrategy":"validation","validationCode":"boolean v2 = Boolean.parseBoolean(String.valueOf(opts.getOrDefault(\"useSwaggerAnnotations\", \"false\")));\nboolean v3 = Boolean.parseBoolean(String.valueOf(opts.getOrDefault(\"useSwaggerV3Annotations\", \"false\")));\nif (v2 && v3) {\n    throw new IllegalArgumentException(\"useSwaggerAnnotations and useSwaggerV3Annotations are mutually exclusive; keep only v3\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    generator.generate();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"mutually exclusive\")) {\n        opts.remove(\"useSwaggerAnnotations\"); // v3 is preferred by the generator\n        generator.generate();\n    } else throw e;\n}","preventionTips":["Model annotation-version choices as a single 'swaggerVersion' input in your wrapper and expand to the exact one flag","When upgrading Swagger 2 to v3, delete the old flag in the same change that adds the new one","Diff merged option maps (base preset + override) before generation to catch resurrected flags"],"tags":["java","jaxrs","openapi-generator","swagger","annotations","configuration","mutually-exclusive"],"backgroundTag":"mutually-exclusive-flags","analyzedSha":"fcec517be3cf5b7964296bcba25fbc97541484e7","analyzedAt":"2026-08-22T11:13:11.613Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}