Repository navigation
fix: honour JSpecify @Nullable on controller parameters - #3378
Open
sharanggupta wants to merge 1 commit into
Open
sharanggupta wants to merge 1 commit into
sharanggupta wants to merge 1 commit into
Conversation
For a controller method parameter, GenericParameterService only forwarded the annotations declared on the parameter's type arguments to swagger-core, never the ones declared on the parameter type itself. A type-use-only annotation such as the JSpecify @nullable (the annotation Spring Framework 7 standardises on) was therefore dropped before schema extraction: Spring already marked the parameter as not required, but its schema stayed non-nullable, unlike the same parameter annotated with Spring's declaration targeted @nullable. Flattened @ParameterObject fields were given both sets of annotations in springdoc#3300. Apply the same treatment to direct parameters by reusing annotationsFromAnnotatedType, made null-safe for the parameters whose AnnotatedType cannot be resolved. The regression app also covers a @PathVariable carrying the same annotation, which the springdoc#3358 guard keeps non-nullable. Fixes springdoc#3377
sharanggupta
force-pushed
the
gh-3377-jspecify-nullable-request-param
branch
from
October 6, 2026 20:58
2ee61c2 to
ada02a0
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A JSpecify
@Nullable(TYPE_USE only, the annotation Spring Framework 7 standardises on) declared on a controller method parameter is dropped before schema extraction. Spring already marks the parameterrequired: false, but its schema stays non-nullable, unlike the same parameter annotated with Spring's declaration-targeted@Nullable(app102). #3300 fixed this for flattened@ParameterObjectfields; this applies the same treatment to direct parameters.Change Plan
GenericParameterService.resolveTypeAndTypeAnnotationsForParameter: forward the annotations on the parameter's ownAnnotatedTypeas well as those on its type arguments, by reusingannotationsFromAnnotatedType(made null-safe for parameters whoseAnnotatedTypecannot be resolved).app274(OAS 3.0 and 3.1) with@RequestParam @Nullable String/Integerusingorg.jspecify.annotations.Nullable; expected["string","null"]/nullable: true. The same app has a@PathVariable @Nullable String idendpoint whose golden file shows the path parameter staysrequired: trueand non-nullable, becauseSpringDocUtils.fixNullablePathParameter(nullable: true dropped for @Nullable @PathVariable parameters when using springdoc.api-docs.version=openapi-3-0 (regression in 3.1.1) #3358) still applies after this change.Annotations that target both PARAMETER and TYPE_USE (for example
@Size) now appear in the merged annotation array for direct parameters the same way they already do for@ParameterObjectfields since #3300; the existing suites (including app270'sList<@Pattern String>) are unchanged.Test Plan
SpringDocApp274Testfails onmain(schema.type Expected: a JSON array got: string/Expected: nullable but none found) and passes with the fix.springdoc-openapi-starter-common(55 tests) andspringdoc-openapi-starter-webmvc-api(655 tests) suites are green.Fixes #3377