LocalTime, YearMonth, MonthDay are not serialized correctly in ISO 8601 format. Fixes #2938

Author: bnasslahsen

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/configuration/SpringDocConfiguration.java

@@ -130,6 +130,7 @@
 import static org.springdoc.core.utils.Constants.GLOBAL_OPEN_API_CUSTOMIZER;
 import static org.springdoc.core.utils.Constants.SPRINGDOC_DEPRECATING_CONVERTER_ENABLED;
 import static org.springdoc.core.utils.Constants.SPRINGDOC_ENABLED;
+import static org.springdoc.core.utils.Constants.SPRINGDOC_ENABLE_EXTRA_SCHEMAS;
 import static org.springdoc.core.utils.Constants.SPRINGDOC_POLYMORPHIC_CONVERTER_ENABLED;
 import static org.springdoc.core.utils.Constants.SPRINGDOC_SCHEMA_RESOLVE_PROPERTIES;
 import static org.springdoc.core.utils.Constants.SPRINGDOC_SHOW_ACTUATOR;
@@ -158,6 +159,14 @@ public class SpringDocConfiguration {
 				.addResponseWrapperToIgnore(Future.class);
 	}
 
+	@Bean
+	@Lazy(false)
+	@ConditionalOnProperty(name = SPRINGDOC_ENABLE_EXTRA_SCHEMAS, matchIfMissing = true)
+	Object initExtraSchemas() {
+		getConfig().initExtraSchemas();
+		return null;
+	}
+	
 	/**
 	 * Springdoc bean factory post processor bean factory post processor.
 	 *

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/extractor/MethodParameterPojoExtractor.java

@@ -35,7 +35,15 @@
 import java.lang.reflect.TypeVariable;
 import java.nio.charset.Charset;
 import java.time.Duration;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
 import java.time.LocalTime;
+import java.time.MonthDay;
+import java.time.OffsetTime;
+import java.time.Period;
+import java.time.Year;
+import java.time.YearMonth;
+import java.time.ZoneOffset;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collection;
@@ -49,6 +57,7 @@
 import java.util.OptionalInt;
 import java.util.OptionalLong;
 import java.util.Set;
+import java.util.TimeZone;
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.concurrent.atomic.AtomicLong;
 import java.util.function.Predicate;
@@ -96,8 +105,17 @@ public class MethodParameterPojoExtractor {
 		SIMPLE_TYPES.add(Iterable.class);
 		SIMPLE_TYPES.add(Duration.class);
 		SIMPLE_TYPES.add(LocalTime.class);
+		SIMPLE_TYPES.add(LocalDateTime.class);
+		SIMPLE_TYPES.add(LocalDate.class);
+		SIMPLE_TYPES.add(YearMonth.class);
+		SIMPLE_TYPES.add(MonthDay.class);
+		SIMPLE_TYPES.add(Year.class);
 		SIMPLE_TYPES.add(Class.class);
-
+		SIMPLE_TYPES.add(Period.class);    
+		SIMPLE_TYPES.add(OffsetTime.class);
+		SIMPLE_TYPES.add(ZoneOffset.class);
+		SIMPLE_TYPES.add(TimeZone.class);
+		
 		SIMPLE_TYPE_PREDICATES.add(Class::isPrimitive);
 		SIMPLE_TYPE_PREDICATES.add(Class::isEnum);
 		SIMPLE_TYPE_PREDICATES.add(Class::isArray);

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/properties/SpringDocConfigProperties.java

@@ -274,6 +274,29 @@ public class SpringDocConfigProperties {
 	 */
 	private OpenAPI OpenApi;
 
+	/**
+	 * The Enable extra schemas resolution.
+	 */
+	private boolean enableExtraSchemas;
+
+	/**
+	 * Is enable additional schemas resolution boolean.
+	 *
+	 * @return the boolean
+	 */
+	public boolean isEnableExtraSchemas() {
+		return enableExtraSchemas;
+	}
+
+	/**
+	 * Sets enable additional schemas resolution.
+	 *
+	 * @param enableExtraSchemas the enable additional schemas resolution
+	 */
+	public void setEnableExtraSchemas(boolean enableExtraSchemas) {
+		this.enableExtraSchemas = enableExtraSchemas;
+	}
+
 	/**
 	 * Gets open api.
 	 *

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/utils/Constants.java

@@ -424,6 +424,11 @@ public final class Constants {
 	 */
 	public static final String SPRINGDOC_NULLABLE_REQUEST_PARAMETER_ENABLED = "springdoc.nullable-request-parameter-enabled";
 
+	/**
+	 * The constant SPRINGDOC_ENABLE_ADDITIONAL_SCHEMAS_RESOLUTION.
+	 */
+	public static final String SPRINGDOC_ENABLE_EXTRA_SCHEMAS = "springdoc.enable-extra-schemas";
+	
 	/**
 	 * Instantiates a new Constants.
 	 */

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/utils/SpringDocUtils.java

@@ -27,13 +27,26 @@
 package org.springdoc.core.utils;
 
 import java.lang.annotation.Annotation;
+import java.nio.charset.Charset;
+import java.time.Duration;
+import java.time.LocalTime;
+import java.time.MonthDay;
+import java.time.OffsetTime;
+import java.time.Period;
+import java.time.Year;
+import java.time.YearMonth;
+import java.time.ZoneId;
+import java.time.ZoneOffset;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Locale;
+import java.util.TimeZone;
 import java.util.function.Predicate;
 
 import io.swagger.v3.core.converter.AnnotatedType;
 import io.swagger.v3.oas.models.media.Content;
 import io.swagger.v3.oas.models.media.Schema;
+import io.swagger.v3.oas.models.media.StringSchema;
 import org.apache.commons.lang3.ArrayUtils;
 import org.apache.commons.lang3.StringUtils;
 import org.jetbrains.annotations.NotNull;
@@ -356,6 +369,19 @@ public SpringDocUtils removeFromSchemaMap(Class<?> clazz) {
 		return this;
 	}
 
+	/**
+	 * Remove from schema map spring doc utils.
+	 *
+	 * @param classes the clazz
+	 * @return the spring doc utils
+	 */
+	public SpringDocUtils removeFromSchemaMap(Class<?>... classes) {
+		for (Class<?> aClass : classes) {
+			AdditionalModelsConverter.removeFromSchemaMap(aClass);
+		}
+		return this;
+	}
+
 	/**
 	 * Remove from schema class spring doc utils.
 	 *
@@ -502,5 +528,36 @@ public static void handleSchemaTypes(Content content) {
 			});
 		}
 	}
+
+	/**
+	 * Init extra schemas.
+	 */
+	public SpringDocUtils initExtraSchemas() {
+		replaceWithSchema(LocalTime.class, new StringSchema().example("14:30:00"));
+		replaceWithSchema(YearMonth.class, new StringSchema().example("2025-03"));
+		replaceWithSchema(MonthDay.class, new StringSchema().example("--03-22"));
+		replaceWithSchema(Year.class, new StringSchema().example("2025"));
+		replaceWithSchema(Duration.class, new StringSchema().example("PT2H30M"));
+		replaceWithSchema(Period.class, new StringSchema().example("P2Y3M"));
+		replaceWithSchema(OffsetTime.class, new StringSchema().example("14:30:00+01:00"));
+		replaceWithSchema(ZoneId.class, new StringSchema().example("Europe/Paris"));
+		replaceWithSchema(ZoneOffset.class, new StringSchema().example("+01:00"));
+		replaceWithSchema(TimeZone.class, new StringSchema().example("GMT"));
+		replaceWithSchema(Charset.class, new StringSchema().example("UTF-8"));
+		replaceWithSchema(Locale.class, new StringSchema().example("en-US"));
+		return this;
+	}
+
+	/**
+	 * Reset extra schemas spring doc utils.
+	 *
+	 * @return the spring doc utils
+	 */
+	public SpringDocUtils resetExtraSchemas() {
+		SpringDocUtils.getConfig().removeFromSchemaMap(LocalTime.class,YearMonth.class,
+				MonthDay.class, Year.class, Duration.class, Period.class, OffsetTime.class,
+				ZoneId.class, ZoneOffset.class, TimeZone.class, Charset.class, Locale.class);
+		return this;
+	}
 }
 

springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v30/app115/JavaTimeOperationCustomizer.java

@@ -46,7 +46,6 @@ public Operation customize(Operation operation, HandlerMethod handlerMethod) {
 				Content content = response.getContent();
 				if (content.containsKey(MediaType.APPLICATION_JSON_VALUE)) {
 					Schema schema = content.get(MediaType.APPLICATION_JSON_VALUE).getSchema();
-					schema.getProperties().clear();
 					schema.setType("string");
 				}
 			}

springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v30/app115/SpringDocApp115Test.java

@@ -27,8 +27,11 @@
 import test.org.springdoc.api.v30.AbstractSpringDocV30Test;
 
 import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.test.context.TestPropertySource;
 
+import static org.springdoc.core.utils.Constants.SPRINGDOC_ENABLE_EXTRA_SCHEMAS;
 
+@TestPropertySource(properties = SPRINGDOC_ENABLE_EXTRA_SCHEMAS + "=true")
 public class SpringDocApp115Test extends AbstractSpringDocV30Test {
 
 	@SpringBootApplication

springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v31/app115/SpringDocApp115Test.java

@@ -24,13 +24,30 @@
 
 package test.org.springdoc.api.v31.app115;
 
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
 import test.org.springdoc.api.v31.AbstractSpringDocTest;
 
 import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.test.context.TestPropertySource;
 
+import static org.springdoc.core.utils.Constants.SPRINGDOC_ENABLE_EXTRA_SCHEMAS;
+import static org.springdoc.core.utils.SpringDocUtils.getConfig;
 
+@TestPropertySource(properties = SPRINGDOC_ENABLE_EXTRA_SCHEMAS + "=false")
 public class SpringDocApp115Test extends AbstractSpringDocTest {
 
+	@BeforeAll
+	public static void clear() {
+		getConfig().resetExtraSchemas();
+	}
+
+	@AfterAll
+	public static void restore() {
+		getConfig().initExtraSchemas();
+	}
+
+	
 	@SpringBootApplication
 	static class SpringDocTestApp {}
 

springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v31/app243/HelloController.java

@@ -0,0 +1,26 @@
+package test.org.springdoc.api.v31.app243;
+
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.LocalTime;
+import java.time.MonthDay;
+import java.time.Year;
+import java.time.YearMonth;
+
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+public class HelloController {
+
+	@PostMapping("/time1")
+	public TimeDtoNoAnnotations postTime1(@RequestBody TimeDtoNoAnnotations timeDto) {
+		return timeDto;
+	}
+
+	public record TimeDtoNoAnnotations (LocalDateTime localDateTime, 
+										LocalDate localDate, LocalTime localTime,
+										YearMonth yearMonth, MonthDay monthDay, Year year) {
+	}
+}

springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v31/app243/SpringDocApp243Test.java

@@ -0,0 +1,37 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  *
+ *  *  *  *  *  * Copyright 2019-2025 the original author or authors.
+ *  *  *  *  *  *
+ *  *  *  *  *  * Licensed under the Apache License, Version 2.0 (the "License");
+ *  *  *  *  *  * you may not use this file except in compliance with the License.
+ *  *  *  *  *  * You may obtain a copy of the License at
+ *  *  *  *  *  *
+ *  *  *  *  *  *      https://www.apache.org/licenses/LICENSE-2.0
+ *  *  *  *  *  *
+ *  *  *  *  *  * Unless required by applicable law or agreed to in writing, software
+ *  *  *  *  *  * distributed under the License is distributed on an "AS IS" BASIS,
+ *  *  *  *  *  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  *  *  *  *  * See the License for the specific language governing permissions and
+ *  *  *  *  *  * limitations under the License.
+ *  *  *  *  *
+ *  *  *  *
+ *  *  *
+ *  *
+ *  
+ */
+
+package test.org.springdoc.api.v31.app243;
+
+import test.org.springdoc.api.v31.AbstractSpringDocTest;
+
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+public class SpringDocApp243Test extends AbstractSpringDocTest {
+
+	@SpringBootApplication
+	static class SpringDocTestApp {}
+}

springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.0.1/app115.json

@@ -24,7 +24,7 @@
               "application/json": {
                 "schema": {
                   "type": "string",
-                  "properties": {}
+                  "example": "PT2H30M"
                 }
               }
             }

springdoc-openapi-starter-webmvc-api/src/test/resources/results/3.1.0/app243.json

@@ -0,0 +1,78 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "OpenAPI definition",
+    "version": "v0"
+  },
+  "servers": [
+    {
+      "url": "http://localhost",
+      "description": "Generated server url"
+    }
+  ],
+  "paths": {
+    "/time1": {
+      "post": {
+        "tags": [
+          "hello-controller"
+        ],
+        "operationId": "postTime1",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TimeDtoNoAnnotations"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "*/*": {
+                "schema": {
+                  "$ref": "#/components/schemas/TimeDtoNoAnnotations"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "TimeDtoNoAnnotations": {
+        "type": "object",
+        "properties": {
+          "localDateTime": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "localDate": {
+            "type": "string",
+            "format": "date"
+          },
+          "localTime": {
+            "type": "string",
+            "example": "14:30:00"
+          },
+          "yearMonth": {
+            "type": "string",
+            "example": "2025-03"
+          },
+          "monthDay": {
+            "type": "string",
+            "example": "--03-22"
+          },
+          "year": {
+            "type": "string",
+            "example": "2025"
+          }
+        }
+      }
+    }
+  }
+}