OpenAPITools / OpenAPITools/openapi-generator

[BUG] [Spring] Invalid Interface generation when parameters are removed by x-spring-paginated

Open
#21,274 4 comments 1 reaction 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

Bug Report Checklist
  • Have you provided a full/minimal spec to reproduce the issue?
  • Have you validated the input using an OpenAPI validator?
  • Have you tested with the latest master to confirm the issue still exists?
  • Have you searched for related issues/PRs?
  • What's the actual output vs expected output?
  • [Optional] Sponsorship to speed up the bug fix or feature request (example)
Description

The interface for an API that is annotated with x-spring-paginated and has no other query parameters than page and size is generated with a method parameter list that contains an extra comma (,), causing compilation errors.
The expected class should not have the extra comma.
Passing extra parameters, any empty array of parameters or no parameters at all doesn't cause the issue.
No validation problems.
It seems that is working on the latest master but don't see any changes to the spring generator classes done after release 7.13.0.

/**
 * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech) (7.13.0).
 * https://openapi-generator.tech
 * Do not edit the class manually.
 */
package com.example.api;

import org.springframework.data.domain.Pageable;
import org.springdoc.core.annotations.ParameterObject;
import com.example.model.ResourceListResponseDto;
import io.swagger.v3.oas.annotations.ExternalDocumentation;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.media.ArraySchema;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.media.ExampleObject;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.HttpStatus;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
import org.springframework.http.codec.multipart.Part;

import jakarta.validation.Valid;
import jakarta.validation.constraints.*;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import jakarta.annotation.Generated;

@Generated(value = "org.openapitools.codegen.languages.SpringCodegen", date = "2025-05-13T11:25:32.754714+02:00[Europe/Rome]", comments = "Generator version: 7.13.0")
@Validated
@Tag(name = "resource", description = "the resource API")
public interface ResourceApi {

    /**
     * GET /resource : Retrieves a resource with pagination parameters
     * Retrieves a resource with pagination parameters
     *
     * @return Successful operation (status code 200)
     */
    @Operation(
        operationId = "retrieveResource",
        summary = "Retrieves a resource with pagination parameters",
        description = "Retrieves a resource with pagination parameters",
        responses = {
            @ApiResponse(responseCode = "200", description = "Successful operation", content = {
                @Content(mediaType = "application/json", schema = @Schema(implementation = ResourceListResponseDto.class))
            })
        }
    )
    @RequestMapping(
        method = RequestMethod.GET,
        value = "/resource",
        produces = { "application/json" }
    )
    @ResponseStatus(HttpStatus.OK)
    
    Mono<ResourceListResponseDto> _retrieveResource(
        ,
        @Parameter(hidden = true) final ServerWebExchange exchange,
        @ParameterObject final Pageable pageable
    );

}

No validation issues for the spec:

java -jar .\openapi-generator-cli.jar validate -i .\src\main\resources\openapi\parameters-issue.yaml
Validating spec (.\src\main\resources\openapi\parameters-issue.yaml)
No validation issues detected.
openapi-generator version
  • Version 7.13 via openapi-generator-maven-plugin
OpenAPI declaration file content or url
openapi: 3.0.4
info:
  title: Parameter removal issue
  description: |-
    Demonstrating parameter removal issue when using x-spring-paginated: true
  version: 1.0.0
paths:
  /resource:
    get:
      x-spring-paginated: true
      summary: Retrieves a resource with pagination parameters
      description: Retrieves a resource with pagination parameters
      operationId: retrieveResource
      parameters:
        - $ref: "#/components/parameters/page"
        - $ref: "#/components/parameters/size"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceListResponse"
components:
  schemas:
    ResourceListResponse:
      type:
        object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Resource"
    Resource:
      type: object
      properties:
        id:
          type: string
        createDate:
          type: string
          format: date-time
        updateDate:
          type: string
          format: date-time
  parameters:
    page:
      in: query
      required: false
      name: page
      description: Requested page in a list of data
      schema:
        type: integer
    size:
      in: query
      required: false
      name: size
      description: Requested page-size in a list of data
      schema:
        type: integer
Generation Details
  • Language: spring
  • Tool: openapi-generator-maven-plugin
    Configuration:
<build>
	<plugins>
		<plugin>
			<groupId>org.openapitools</groupId>
			<artifactId>openapi-generator-maven-plugin</artifactId>
			<version>${openapi-generator-maven-plugin.version}</version>
			<executions>
				<execution>
					<id>generate-parameters-issue-api</id>
					<goals>
						<goal>generate</goal>
					</goals>
					<configuration>
						<inputSpec>${project.basedir}/src/main/resources/openapi/parameters-issue.yaml</inputSpec>
						<generatorName>spring</generatorName>
						<apiPackage>com.example.api</apiPackage>
						<modelPackage>com.example.model</modelPackage>
						<modelNameSuffix>Dto</modelNameSuffix>
						<configOptions>
							<interfaceOnly>true</interfaceOnly>
							<skipDefaultInterface>true</skipDefaultInterface>
							<useSpringBoot3>true</useSpringBoot3>
							<reactive>true</reactive>
							<delegatePattern>true</delegatePattern>
							<dateLibrary>java8</dateLibrary>
							<useResponseEntity>false</useResponseEntity>
						</configOptions>
					</configuration>
				</execution>
			</executions>
		</plugin>
	</plugins>
</build>

Steps to reproduce
  1. Create a spring project
  2. Add the specs in file src/main/resources/openapi/parameters-issue.yaml
  3. Run the generator via mvn openapi-generator:generate@generate-parameters-issue-api
Related issues/PRs

I wasn't able to find any similar issue

Suggest a fix

Might it be that the way the pageable-related parameters are removed leaves the list in a state that is not considered completely empty by the template that renders the class?

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 src/main/resources/openapi/parameters-issue.yaml and run mvn openapi-generator:generate@generate-parameters-issue-api using the reported Spring configuration. Inspect the generated ResourceApi method signature and trace how x-spring-paginated removes page and size parameters. Done means the generated interface has no stray comma and compiles for this reproduction case.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, spring, yaml
Domain
api, backend, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
64/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.