[Java][jaxrs-spec] add JSpecify support

jaxrs-spec had no jspecify support at all — no `useJspecify` option, and
the generator emitted no nullability annotations for any library. This
adds it generator-wide rather than per-library, because the model and
parameter templates are shared by all six libraries (default, quarkus,
thorntail, openliberty, helidon, kumuluzee); only quarkus overrides
formParams.

- JavaJAXRSSpecServerCodegen: `useJspecify` cliOption, applyJspecify()
  and the Nullable imports for models and operations.
- Shared pojo.mustache (field, getter, setter, fluent setter) and the
  six parameter partials, plus the quarkus formParams override.
- New JavaJaxRS/spec copies of modelPackageInfo/apiPackageInfo and the
  nullable* partials: unlike the java client libraries, which all share
  one `Java` template dir, jaxrs-spec has its own with no fallback.
- Base pom swaps jsr305 for jspecify under the flag, matching how the
  java client libraries handle it; the quarkus pom adds jspecify.

applyJspecify() must run *after* the `supportingFiles.clear()` in
processOpts(), which would otherwise drop the @NullMarked package-info
files.

jaxrs-cxf-cdi extends this generator but uses its own cxf-cdi template
directory, so it would have advertised the option without honouring it —
the exact defect this change fixes elsewhere. It calls removeOption,
alongside the existing removeOption(GENERATE_JSON_CREATOR).

Every template change is guarded by {{#useJspecify}}: flag-off output is
byte-identical to before, verified by diffing against a jar built from
the parent branch for both the default and quarkus libraries.

Adds a sample (jaxrs-spec-quarkus-jspecify, registered in samples-jdk17
since the quarkus library targets Java 17) and two tests covering the
annotations, type-use placement on qualified types, and that the flag
off still emits jsr305 and no annotations.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQa4EUVfxzqe4qi9PDj5RU

Author: Ignacio-Vidal

.github/workflows/samples-jdk17.yaml

@@ -24,6 +24,7 @@ on:
       - samples/server/petstore/java-helidon-server/v3/se/**
       - samples/server/petstore/jaxrs-spec-sealed/**
       - samples/server/petstore/jaxrs-spec/quarkus-security/**
+      - samples/server/petstore/jaxrs-spec-quarkus-jspecify/**
   pull_request:
     paths:
       # clients
@@ -48,6 +49,7 @@ on:
       - samples/server/petstore/java-helidon-server/v3/se/**
       - samples/server/petstore/jaxrs-spec-sealed/**
       - samples/server/petstore/jaxrs-spec/quarkus-security/**
+      - samples/server/petstore/jaxrs-spec-quarkus-jspecify/**
 jobs:
   build:
     name: Build with JDK17
@@ -78,6 +80,7 @@ jobs:
           - samples/server/petstore/java-helidon-server/v3/se
           - samples/server/petstore/jaxrs-spec-sealed
           - samples/server/petstore/jaxrs-spec/quarkus-security
+          - samples/server/petstore/jaxrs-spec-quarkus-jspecify
     steps:
       - uses: actions/checkout@v7
       - uses: actions/setup-java@v6.0.0

bin/configs/jaxrs-spec-quarkus-jspecify.yaml

@@ -0,0 +1,16 @@
+generatorName: jaxrs-spec
+outputDir: samples/server/petstore/jaxrs-spec-quarkus-jspecify
+inputSpec: modules/openapi-generator/src/test/resources/3_0/java/jspecify.yaml
+templateDir: modules/openapi-generator/src/main/resources/JavaJaxRS/spec
+validateSpec: false
+additionalProperties:
+  artifactId: jaxrs-spec-quarkus-jspecify
+  library: "quarkus"
+  hideGenerationTimestamp: "true"
+  interfaceOnly: "true"
+  useJakartaEe: "true"
+  useJspecify: "true"
+  openApiNullable: "false"
+  dateLibrary: "java8"
+typeMappings:
+  BigDecimal: java.math.BigDecimal

docs/generators/jaxrs-spec.md

@@ -86,6 +86,7 @@ These options may be applied as additional-properties (cli) or configOptions (pl
 |useEnumCaseInsensitive|Use `equalsIgnoreCase` when String for enum comparison| |false|
 |useJakartaEe|whether to use Jakarta EE namespace instead of javax| |false|
 |useJakartaSecurityAnnotations|Whether to generate Jakarta security annotations (@RolesAllowed, @PermitAll). Requires useJakartaEe=true. Currently only supported when library is set to quarkus.| |false|
+|useJspecify|Use JSpecify for null checks: @NullMarked package-info and @Nullable on optional properties and parameters.| |false|
 |useMicroProfileOpenAPIAnnotations|Whether to generate Microprofile OpenAPI annotations. Only valid when library is set to quarkus.| |false|
 |useMutiny|Whether to use Smallrye Mutiny instead of CompletionStage for asynchronous computation. Only valid when library is set to quarkus.| |false|
 |useOneOfInterfaces|whether to use a java interface to describe a set of oneOf options, where each option is a class that implements the interface| |false|

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaJAXRSCXFCDIServerCodegen.java

@@ -64,6 +64,9 @@ public JavaJAXRSCXFCDIServerCodegen() {
         embeddedTemplateDir = templateDir = JAXRS_TEMPLATE_DIRECTORY_NAME + File.separator + "cxf-cdi";
 
         removeOption(JavaJAXRSSpecServerCodegen.GENERATE_JSON_CREATOR);
+        // jspecify support lives in the JavaJaxRS/spec templates; this generator uses its own
+        // cxf-cdi template directory, so the option would be advertised but have no effect.
+        removeOption(USE_JSPECIFY);
     }
 
     @Override

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/JavaJAXRSSpecServerCodegen.java

@@ -171,6 +171,7 @@ public JavaJAXRSSpecServerCodegen() {
         cliOptions.add(CliOption.newBoolean(GENERATE_JSON_CREATOR, "Whether to generate @JsonCreator constructor for required properties.", generateJsonCreator));
         cliOptions.add(CliOption.newBoolean(USE_ENUM_CASE_INSENSITIVE, "Use `equalsIgnoreCase` when String for enum comparison", useEnumCaseInsensitive));
         cliOptions.add(CliOption.newBoolean(USE_SEALED, "Whether to generate sealed model interfaces and classes.", useSealed));
+        cliOptions.add(CliOption.newBoolean(USE_JSPECIFY, "Use JSpecify for null checks: @NullMarked package-info and @Nullable on optional properties and parameters.", useJspecify));
     }
 
     @Override
@@ -255,6 +256,11 @@ public void processOpts() {
         supportingFiles.add(new SupportingFile("README.mustache", "", "README.md")
                 .doNotOverwrite());
 
+        // after the clear() above, which would otherwise drop the @NullMarked package-info files
+        if (useJspecify) {
+            applyJspecify();
+        }
+
         if ((!interfaceOnly) || generateRootResources) {
             supportingFiles.add(new SupportingFile("RestResourceRoot.mustache",
                     (sourceFolder + '/' + invokerPackage).replace(".", "/"), "RestResourceRoot.java")
@@ -348,6 +354,10 @@ public CodegenModel fromModel(String name, Schema model) {
             codegenModel.imports.remove("JsonProperty");
             codegenModel.imports.remove("JsonTypeName");
         }
+        if (useJspecify) {
+            codegenModel.imports.add("Nullable");
+        }
+
         return codegenModel;
     }
 
@@ -481,6 +491,18 @@ public CodegenOperation fromOperation(String path, String httpMethod, Operation
         if (QUARKUS_LIBRARY.equals(getLibrary()) && useJakartaSecurityAnnotations) {
             jakartaSecurityAnnotationProcessor.applyTo(op, operation, openAPI);
         }
+        if (useJspecify) {
+            addNullableImportForOperation(op);
+        }
         return op;
     }
+
+    @Override
+    protected void applyJspecify() {
+        super.applyJspecify();
+        // nullable_var_annotations.mustache emits @{{javaxPackage}}.annotation.Nullable; the lambda
+        // finds that and re-injects a bare @Nullable in type-use position, so tell it what to look for.
+        jSpecifyNullableLambda.setNullableAnnotation("@" + additionalProperties.get(JAVAX_PACKAGE) + ".annotation.Nullable");
+    }
+
 }

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/apiPackageInfo.mustache

@@ -0,0 +1,2 @@
+@org.jspecify.annotations.NullMarked
+package {{apiPackage}};

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/bodyParams.mustache

@@ -1 +1 @@
-{{#isBodyParam}}{{#isDeprecated}}@Deprecated {{/isDeprecated}}{{#useBeanValidation}}@Valid {{#required}}{{^isNullable}}@NotNull {{/isNullable}}{{/required}}{{/useBeanValidation}}{{{dataType}}} {{paramName}}{{/isBodyParam}}
+{{#isBodyParam}}{{#isDeprecated}}@Deprecated {{/isDeprecated}}{{#useBeanValidation}}@Valid {{#required}}{{^isNullable}}@NotNull {{/isNullable}}{{/required}}{{/useBeanValidation}}{{#useJspecify}}{{>nullable_var_annotations}}{{/useJspecify}}{{>nullableDataType}} {{paramName}}{{/isBodyParam}}

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/cookieParams.mustache

@@ -1 +1 @@
-{{#isCookieParam}}{{#isDeprecated}}@Deprecated {{/isDeprecated}}@CookieParam("{{baseName}}"){{#useBeanValidation}}{{>beanValidationQueryParams}}{{/useBeanValidation}}{{^isContainer}}{{#defaultValue}} @DefaultValue("{{{.}}}"){{/defaultValue}}{{/isContainer}} {{#useSwaggerAnnotations}}{{#description}} @ApiParam("{{.}}"){{/description}}{{/useSwaggerAnnotations}}{{#useMicroProfileOpenAPIAnnotations}}{{#description}} @org.eclipse.microprofile.openapi.annotations.parameters.Parameter(description="{{.}}"){{/description}}{{/useMicroProfileOpenAPIAnnotations}}  {{{dataType}}} {{paramName}}{{/isCookieParam}}
+{{#isCookieParam}}{{#isDeprecated}}@Deprecated {{/isDeprecated}}@CookieParam("{{baseName}}"){{#useBeanValidation}}{{>beanValidationQueryParams}}{{/useBeanValidation}}{{^isContainer}}{{#defaultValue}} @DefaultValue("{{{.}}}"){{/defaultValue}}{{/isContainer}} {{#useSwaggerAnnotations}}{{#description}} @ApiParam("{{.}}"){{/description}}{{/useSwaggerAnnotations}}{{#useMicroProfileOpenAPIAnnotations}}{{#description}} @org.eclipse.microprofile.openapi.annotations.parameters.Parameter(description="{{.}}"){{/description}}{{/useMicroProfileOpenAPIAnnotations}}  {{#useJspecify}}{{>nullable_var_annotations}}{{/useJspecify}}{{>nullableDataType}} {{paramName}}{{/isCookieParam}}

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/formParams.mustache

@@ -1,2 +1,2 @@
 {{#isFormParam}}
-{{#isDeprecated}}@Deprecated {{/isDeprecated}}{{^isFile}}@FormParam(value = "{{baseName}}")  {{{dataType}}} {{paramName}}{{/isFile}}{{#isFile}}@FormParam(value = "{{baseName}}") InputStream {{paramName}}InputStream{{/isFile}}{{/isFormParam}}
+{{#isDeprecated}}@Deprecated {{/isDeprecated}}{{^isFile}}@FormParam(value = "{{baseName}}")  {{#useJspecify}}{{>nullable_var_annotations}}{{/useJspecify}}{{>nullableDataType}} {{paramName}}{{/isFile}}{{#isFile}}@FormParam(value = "{{baseName}}") InputStream {{paramName}}InputStream{{/isFile}}{{/isFormParam}}

modules/openapi-generator/src/main/resources/JavaJaxRS/spec/headerParams.mustache

@@ -1 +1 @@
-{{#isHeaderParam}}{{#isDeprecated}}@Deprecated {{/isDeprecated}}@HeaderParam("{{baseName}}"){{#useBeanValidation}}{{>beanValidationHeaderParams}}{{/useBeanValidation}} {{#defaultValue}} @DefaultValue("{{{.}}}"){{/defaultValue}} {{#useSwaggerAnnotations}}{{#description}} @ApiParam("{{.}}"){{/description}}{{/useSwaggerAnnotations}}{{#useMicroProfileOpenAPIAnnotations}}{{#description}} @org.eclipse.microprofile.openapi.annotations.parameters.Parameter(description="{{.}}"){{/description}}{{/useMicroProfileOpenAPIAnnotations}} {{{dataType}}} {{paramName}}{{/isHeaderParam}}
+{{#isHeaderParam}}{{#isDeprecated}}@Deprecated {{/isDeprecated}}@HeaderParam("{{baseName}}"){{#useBeanValidation}}{{>beanValidationHeaderParams}}{{/useBeanValidation}} {{#defaultValue}} @DefaultValue("{{{.}}}"){{/defaultValue}} {{#useSwaggerAnnotations}}{{#description}} @ApiParam("{{.}}"){{/description}}{{/useSwaggerAnnotations}}{{#useMicroProfileOpenAPIAnnotations}}{{#description}} @org.eclipse.microprofile.openapi.annotations.parameters.Parameter(description="{{.}}"){{/description}}{{/useMicroProfileOpenAPIAnnotations}} {{#useJspecify}}{{>nullable_var_annotations}}{{/useJspecify}}{{>nullableDataType}} {{paramName}}{{/isHeaderParam}}