{"record":{"id":"415de48390af9e82","repo":"OpenAPITools/openapi-generator","slug":"flags-useswaggerv3annotations-and-usemicroprofi","errorCode":null,"errorMessage":"Flags 'useSwaggerV3Annotations' and 'useMicroProfileOpenAPIAnnotations' are mutually exclusive. Please enable only one.","messagePattern":"Flags 'useSwaggerV3Annotations' and 'useMicroProfileOpenAPIAnnotations' 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":201,"sourceCode":"            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)) {\n            openApiSpecFileLocation = additionalProperties.get(OPEN_API_SPEC_FILE_LOCATION).toString();\n        } else if (QUARKUS_LIBRARY.equals(library) || THORNTAIL_LIBRARY.equals(library) || HELIDON_LIBRARY.equals(library) || KUMULUZEE_LIBRARY.equals(library)) {\n            openApiSpecFileLocation = \"src/main/resources/META-INF/openapi.yaml\";","sourceCodeStart":183,"sourceCodeEnd":219,"githubUrl":"https://github.com/OpenAPITools/openapi-generator/blob/fcec517be3cf5b7964296bcba25fbc97541484e7/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaJAXRSSpecServerCodegen.java#L183-L219","documentation":"Thrown by JavaJAXRSSpecServerCodegen.processOpts when useSwaggerV3Annotations and useMicroProfileOpenAPIAnnotations are both true. The two annotation systems (Swagger Core v3 vs org.eclipse.microprofile.openapi) cover the same purpose — documenting JAX-RS endpoints — and the templates pick one emitter, so combining them produces duplicated/conflicting annotations. Unlike the v2/v3 pair, there is no auto-preference: both truthy means an error.","triggerScenarios":"Passing --additional-properties useSwaggerV3Annotations=true,useMicroProfileOpenAPIAnnotations=true to -g jaxrs-jersey (especially with --library quarkus, where the MicroProfile flag is explicitly read via convertPropertyToBooleanAndWriteBack). Also via config files merged from a Quarkus template that already enables MicroProfile annotations.","commonSituations":"Quarkus projects: Quarkus natively consumes MP OpenAPI annotations, but devs add swagger-v3 annotations for swagger-codegen tooling and enable both. Config inheritance from a shared base preset plus per-service overrides re-enables the deleted flag.","solutions":["For Quarkus, prefer useMicroProfileOpenAPIAnnotations=true (native to the platform) and remove useSwaggerV3Annotations","For plain JAX-RS/Swagger tooling, keep useSwaggerV3Annotations=true and remove the MicroProfile flag","Check the effective merged options once (CLI flags + --config + configOptions) and delete the redundant key","Document a single annotation standard per generator in your team's config-as-code repo"],"exampleFix":"# before\nopenapi-generator-cli generate -g jaxrs-jersey -i api.yaml --library quarkus \\\n  --additional-properties useSwaggerV3Annotations=true,useMicroProfileOpenAPIAnnotations=true\n\n# after\nopenapi-generator-cli generate -g jaxrs-jersey -i api.yaml --library quarkus \\\n  --additional-properties useMicroProfileOpenAPIAnnotations=true","handlingStrategy":"validation","validationCode":"boolean v3 = Boolean.parseBoolean(String.valueOf(opts.getOrDefault(\"useSwaggerV3Annotations\", \"false\")));\nboolean mp = Boolean.parseBoolean(String.valueOf(opts.getOrDefault(\"useMicroProfileOpenAPIAnnotations\", \"false\")));\nif (v3 && mp) {\n    throw new IllegalArgumentException(\"useSwaggerV3Annotations and useMicroProfileOpenAPIAnnotations are mutually exclusive\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    generator.generate();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"useMicroProfileOpenAPIAnnotations\")) {\n        throw new ConfigException(\"Pick one annotation system: Swagger v3 or MicroProfile OpenAPI\", e);\n    }\n    throw e;\n}","preventionTips":["For Quarkus targets, standardize on MicroProfile OpenAPI annotations and forbid the swagger-v3 flag in presets","Encode 'one documentation framework per project' as a config rule in your generation pipeline","Review annotation options whenever adding a new library flavor to a shared config"],"tags":["java","jaxrs","quarkus","openapi-generator","swagger","microprofile","annotations","mutually-exclusive"],"backgroundTag":"mutually-exclusive-flags","analyzedSha":"fcec517be3cf5b7964296bcba25fbc97541484e7","analyzedAt":"2026-08-22T11:13:11.613Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}