OpenAPITools / OpenAPITools/openapi-generator

[BUG][SpringBoot4] Method parameter is annotated with org.jspecify.annotations.Nullable but include for annotation is missing in generated code

Open
#23,757 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Issue: Bug
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

Description

A parameter of an API method is annotated with org.jspecify.annotations.Nullable annotation but the annotation is not included in the source file using import. That leads to a compile error.

I stripped down the openAPI yml description to an absolute minimum for reproducing the behavior. While doing this I found out that the @Nullable annotation is only generated if the openAPI yml file contains a particular definition in a components: > schemas: part of the yml file.

openapi-generator version

openAPI Gradle plugin 7.22.0

OpenAPI declaration file content or url
openapi: '3.0.3'
info:
  title: Nullable bug demo
  version: '0.0.1'
servers:
  - url: http://localhost:8080/v1

paths:
  /samplecall/{sample-id}:
    put:
      operationId: methodWithNullableParam
      parameters:
        - name: sample-id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK

components:
  schemas:
    SampleResponse:
      allOf:
        - type: object

(for YAML code)

Generation Details

The source code for the openAPI yml ist generated using the Gradle task "generateSampleApi" and is then located under build/generated/error-nullable/src/main/java/com.openapi.bug/SamplecallApi.java.

The SampleResponse definition in the yaml file is not referenced by the sample API call. It is enough that it is definied in the yaml to put the @Nullable annotation into the source code. If the components: section is removed from the yaml file, no @Nullable annotation will be generated.

Steps to reproduce

To generate the source code WITH @Nullable annotation:

Ensure the `components' part of the yaml file yml/error-nullable.yml

is the same as shown above.
Executa Gradle task generateSampleApi
Open file build/generated/error-nullable/src/main/java/com.openapi.bug/SamplecallApi.java
Check parameter definition for methodWithNullableParam

To generate the source code WITHOUT @Nullable annotation:

Remove the components: part from the yaml file yml/error-nullable.yml.
Executa Gradle task generateSampleApi
Open file build/generated/error-nullable/src/main/java/com.openapi.bug/SamplecallApi.java
Check parameter definition for methodWithNullableParam

openapigenerator-nullable-bug.zip

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with yml/error-nullable.yml and run the Gradle task generateSampleApi. Compare build/generated/error-nullable/src/main/java/com.openapi.bug/SamplecallApi.java with and without the components.schemas.SampleResponse definition, focusing on the generated @Nullable parameter and its imports. Done means the generated source has the required annotation import and compiles in the reproducing case.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi, spring-boot
Domain
api, backend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.