Add descriptions to org.springdoc.core.converters.Pageable fields

Author: Marcin Zarebski

springdoc-openapi-data-rest/src/main/java/org/springdoc/core/converters/Pageable.java

@@ -18,6 +18,8 @@
 
 package org.springdoc.core.converters;
 
+import io.swagger.v3.oas.annotations.media.ArraySchema;
+import io.swagger.v3.oas.annotations.media.Schema;
 import org.springframework.lang.Nullable;
 
 import javax.validation.constraints.Max;
@@ -31,14 +33,18 @@ public class Pageable {
 
 	@Nullable
 	@Min(0)
+	@Schema(description = "Zero-based page index (0..N)", defaultValue = "0")
 	private Integer page;
 
 	@Nullable
 	@Min(1)
 	@Max(2000)
+	@Schema(description = "The size of the page to be returned", defaultValue = "20")
 	private Integer size;
 
 	@Nullable
+	@ArraySchema(arraySchema = @Schema(description = "Sorting criteria in the format: property(,asc|desc). "
+			+ "Default sort order is ascending. " + "Multiple sort criteria are supported."))
 	private List<String> sort;
 
 	public Pageable(int page, int size, List<String> sort) {
@@ -47,19 +53,19 @@ public Pageable(int page, int size, List<String> sort) {
 		this.sort = sort;
 	}
 
-	public int getPage() {
+	public Integer getPage() {
 		return page;
 	}
 
-	public void setPage(int page) {
+	public void setPage(Integer page) {
 		this.page = page;
 	}
 
-	public int getSize() {
+	public Integer getSize() {
 		return size;
 	}
 
-	public void setSize(int size) {
+	public void setSize(Integer size) {
 		this.size = size;
 	}
 
@@ -68,10 +74,11 @@ public List<String> getSort() {
 	}
 
 	public void setSort(List<String> sort) {
-		if (sort == null)
+		if (sort == null) {
 			this.sort.clear();
-		else
+		} else {
 			this.sort = sort;
+		}
 	}
 
 	public void addSort(String sort) {
@@ -80,11 +87,15 @@ public void addSort(String sort) {
 
 	@Override
 	public boolean equals(Object o) {
-		if (this == o) return true;
-		if (o == null || getClass() != o.getClass()) return false;
+		if (this == o) {
+			return true;
+		}
+		if (o == null || getClass() != o.getClass()) {
+			return false;
+		}
 		Pageable pageable = (Pageable) o;
-		return page == pageable.page &&
-				size == pageable.size &&
+		return Objects.equals(page, pageable.page) &&
+				Objects.equals(size, pageable.size) &&
 				Objects.equals(sort, pageable.sort);
 	}
 

springdoc-openapi-data-rest/src/main/java/org/springdoc/core/converters/PageableAsQueryParam.java

@@ -18,17 +18,22 @@
 
 package org.springdoc.core.converters;
 
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.enums.ParameterIn;
 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 java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * @deprecated Use {@link org.springdoc.api.annotations.ParameterObject} annotation
+ * 		on {@link org.springframework.data.domain.Pageable} method parameter instead.
+ */
+@Deprecated
 @Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
 @Retention(RetentionPolicy.RUNTIME)
 @Parameter(in = ParameterIn.QUERY

springdoc-openapi-data-rest/src/test/resources/results/app2.json

@@ -61,16 +61,21 @@
           "page": {
             "minimum": 0,
             "type": "integer",
-            "format": "int32"
+            "description": "Zero-based page index (0..N)",
+            "format": "int32",
+            "default": 0
           },
           "size": {
             "maximum": 2000,
             "minimum": 1,
             "type": "integer",
-            "format": "int32"
+            "description": "The size of the page to be returned",
+            "format": "int32",
+            "default": 20
           },
           "sort": {
             "type": "array",
+            "description": "Sorting criteria in the format: property(,asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
             "items": {
               "type": "string"
             }

springdoc-openapi-data-rest/src/test/resources/results/app7.json

@@ -25,19 +25,22 @@
             "schema": {
               "minimum": 0,
               "type": "integer",
-              "format": "int32"
+              "description": "Zero-based page index (0..N)",
+              "format": "int32",
+              "default": 0
             }
           },
           {
             "name": "size",
             "in": "query",
             "required": false,
             "schema": {
-              "default": 20,
               "maximum": 2000,
               "minimum": 1,
               "type": "integer",
-              "format": "int32"
+              "description": "The size of the page to be returned",
+              "format": "int32",
+              "default": 20
             }
           },
           {
@@ -46,6 +49,7 @@
             "required": false,
             "schema": {
               "type": "array",
+              "description": "Sorting criteria in the format: property(,asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
               "items": {
                 "type": "string"
               }