fix(spring): generate supporting PagedModel files in config package (can be replaced with custom one via importMapping)

Author: Picazsoo

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

@@ -1207,7 +1207,13 @@ public void preprocessOpenAPI(OpenAPI openAPI) {
         if (SPRING_BOOT.equals(library) && substituteGenericPagedModel) {
             pagedModelRegistry = PagedModelScanUtils.scanPagedModels(openAPI);
             if (!pagedModelRegistry.isEmpty()) {
-                importMapping.putIfAbsent("PagedModel", "org.springframework.data.web.PagedModel");
+                boolean customMapping = importMapping.containsKey("PagedModel");
+                importMapping.putIfAbsent("PagedModel", configPackage + ".PagedModel");
+                if (!customMapping) {
+                    // No custom class provided — generate the simple PagedModel into the config package.
+                    supportingFiles.add(new SupportingFile("pagedModel.mustache",
+                            (sourceFolder + File.separator + configPackage).replace(".", File.separator), "PagedModel.kt"));
+                }
                 // Derive the actual simple class name from the FQN in importMapping so that a
                 // custom mapping (e.g. "PagedModel" → "com.example.MyPagedModel") is respected.
                 // The simple name of the FQN becomes the token used in generated code, and is

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

@@ -872,7 +872,13 @@ public void preprocessOpenAPI(OpenAPI openAPI) {
         if (SPRING_BOOT.equals(library) && substituteGenericPagedModel) {
             pagedModelRegistry = PagedModelScanUtils.scanPagedModels(openAPI);
             if (!pagedModelRegistry.isEmpty()) {
-                importMapping.putIfAbsent("PagedModel", "org.springframework.data.web.PagedModel");
+                boolean customMapping = importMapping.containsKey("PagedModel");
+                importMapping.putIfAbsent("PagedModel", configPackage + ".PagedModel");
+                if (!customMapping) {
+                    // No custom class provided — generate the simple PagedModel into the config package.
+                    supportingFiles.add(new SupportingFile("pagedModel.mustache",
+                            (sourceFolder + File.separator + configPackage).replace(".", java.io.File.separator), "PagedModel.java"));
+                }
                 // Derive the actual simple class name from the FQN in importMapping so that a
                 // custom mapping (e.g. "PagedModel" → "com.example.MyPagedModel") is respected.
                 // The simple name of the FQN becomes the token used in generated code, and is

modules/openapi-generator/src/main/resources/JavaSpring/pagedModel.mustache

@@ -0,0 +1,95 @@
+package {{configPackage}};
+
+import java.util.List;
+
+/**
+ * Simple generic paged response wrapper generated by openapi-generator.
+ *
+ * <p>Holds a page of content items and pagination metadata. Jackson deserializes this from the
+ * standard Spring {@code Page} JSON shape:
+ * <pre>
+ * {
+ *   "content": [...],
+ *   "page": { "size": 20, "totalElements": 100, "totalPages": 5, "number": 0 }
+ * }
+ * </pre>
+ *
+ * <p>To use your own class instead, set {@code importMappings.PagedModel} in the generator config.
+ */
+public class PagedModel<T> {
+
+    private List<T> content;
+    private PageMetadata page;
+
+    public PagedModel() {}
+
+    public PagedModel(List<T> content, PageMetadata page) {
+        this.content = content;
+        this.page = page;
+    }
+
+    public List<T> getContent() {
+        return content;
+    }
+
+    public void setContent(List<T> content) {
+        this.content = content;
+    }
+
+    public PageMetadata getPage() {
+        return page;
+    }
+
+    public void setPage(PageMetadata page) {
+        this.page = page;
+    }
+
+    public static class PageMetadata {
+
+        private long size;
+        private long totalElements;
+        private long totalPages;
+        private long number;
+
+        public PageMetadata() {}
+
+        public PageMetadata(long size, long totalElements, long totalPages, long number) {
+            this.size = size;
+            this.totalElements = totalElements;
+            this.totalPages = totalPages;
+            this.number = number;
+        }
+
+        public long getSize() {
+            return size;
+        }
+
+        public void setSize(long size) {
+            this.size = size;
+        }
+
+        public long getTotalElements() {
+            return totalElements;
+        }
+
+        public void setTotalElements(long totalElements) {
+            this.totalElements = totalElements;
+        }
+
+        public long getTotalPages() {
+            return totalPages;
+        }
+
+        public void setTotalPages(long totalPages) {
+            this.totalPages = totalPages;
+        }
+
+        public long getNumber() {
+            return number;
+        }
+
+        public void setNumber(long number) {
+            this.number = number;
+        }
+    }
+}

modules/openapi-generator/src/main/resources/kotlin-spring/pagedModel.mustache

@@ -0,0 +1,27 @@
+package {{configPackage}}
+
+/**
+ * Simple generic paged response wrapper generated by openapi-generator.
+ *
+ * Holds a page of content items and pagination metadata. Jackson deserializes this from the
+ * standard Spring `Page` JSON shape:
+ * ```json
+ * {
+ *   "content": [...],
+ *   "page": { "size": 20, "totalElements": 100, "totalPages": 5, "number": 0 }
+ * }
+ * ```
+ *
+ * To use your own class instead, set `importMappings.PagedModel` in the generator config.
+ */
+data class PagedModel<T>(
+    val content: List<T>,
+    val page: PageMetadata,
+) {
+    data class PageMetadata(
+        val size: Long,
+        val totalElements: Long,
+        val totalPages: Long,
+        val number: Long,
+    )
+}

modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java

@@ -7242,9 +7242,9 @@ public void substituteGenericPagedModel_importsPagedModelAndItemTypeInApiFile()
         Map<String, File> files = generateFromContract(
                 "src/test/resources/3_0/spring/petstore-paged-model.yaml", SPRING_BOOT, props);
 
-        // The api file must import both PagedModel and the item type
+        // The api file must import both the generated PagedModel and the item type
         JavaFileAssert.assertThat(files.get("UserApi.java"))
-                .fileContains("import org.springframework.data.web.PagedModel")
+                .fileContains("import org.openapitools.configuration.PagedModel")
                 .fileContains("import org.openapitools.model.User");
     }
 
@@ -7336,6 +7336,26 @@ public void substituteGenericPagedModel_respectsSchemaMappingWithImportMappingFo
                 .hasReturnType("ResponseEntity<PagedModel<ExternalUser>>");
     }
 
+    @Test
+    public void substituteGenericPagedModel_generatesPagedModelSupportingFile() throws IOException {
+        Map<String, File> files = generateFromContract(
+                "src/test/resources/3_0/spring/petstore-paged-model.yaml", SPRING_BOOT, commonPagedModelProps());
+
+        assertThat(files).containsKey("PagedModel.java");
+    }
+
+    @Test
+    public void substituteGenericPagedModel_doesNotGeneratePagedModelFileWhenCustomMapping() throws IOException {
+        Map<String, Object> props = commonPagedModelProps();
+
+        Map<String, File> files = generateFromContract(
+                "src/test/resources/3_0/spring/petstore-paged-model.yaml", SPRING_BOOT, props,
+                configurator -> configurator
+                        .addImportMapping("PagedModel", "com.example.custom.MyPagedModel"));
+
+        assertThat(files).doesNotContainKey("PagedModel.java");
+    }
+
     @Test
     public void substituteGenericPagedModel_respectsCustomImportMappingClassName() throws IOException {
         // When the user remaps "PagedModel" to a FQN with a different simple class name,

modules/openapi-generator/src/test/java/org/openapitools/codegen/kotlin/spring/KotlinSpringServerCodegenTest.java

@@ -5604,7 +5604,8 @@ public void substituteGenericPagedModel_importsPagedModelAndItemTypeInApiFile()
         File userApi = files.get("UserApi.kt");
         assertThat(userApi).isNotNull();
         String content = Files.readString(userApi.toPath());
-        assertThat(content).contains("import org.springframework.data.web.PagedModel");
+        // The api file must import the generated PagedModel and the item type
+        assertThat(content).contains("import org.openapitools.configuration.PagedModel");
         assertThat(content).contains("import org.openapitools.model.User");
     }
 
@@ -5682,6 +5683,26 @@ public void substituteGenericPagedModel_respectsSchemaMappingForItemType() throw
         assertThat(content).contains("import com.example.external.ExternalUser");
     }
 
+    @Test
+    public void substituteGenericPagedModel_generatesPagedModelSupportingFile() throws IOException {
+        Map<String, File> files = generateFromContract(
+                "src/test/resources/3_0/spring/petstore-paged-model.yaml", commonKotlinPagedModelProps());
+
+        assertThat(files).containsKey("PagedModel.kt");
+    }
+
+    @Test
+    public void substituteGenericPagedModel_doesNotGeneratePagedModelFileWhenCustomMapping() throws IOException {
+        Map<String, File> files = generateFromContract(
+                "src/test/resources/3_0/spring/petstore-paged-model.yaml",
+                commonKotlinPagedModelProps(),
+                new HashMap<>(),
+                configurator -> configurator
+                        .addImportMapping("PagedModel", "com.example.custom.MyPagedModel"));
+
+        assertThat(files).doesNotContainKey("PagedModel.kt");
+    }
+
     @Test
     public void substituteGenericPagedModel_respectsCustomImportMappingClassName() throws IOException {
         // When the user remaps "PagedModel" to a FQN with a different simple class name,