From 18c22c6ff7a6e1448246a16da89f1dd154c5da87 Mon Sep 17 00:00:00 2001
From: DerManoMann <mano@radebatz.net>
Date: Sun, 16 Nov 2025 23:11:51 +1300
Subject: [PATCH] Treat empty string `''` same as undefined for all string
 based properties

---
 .../specs/petstore/annotations/Models/Pet.php         |  4 +++-
 .../examples/specs/petstore/attributes/Models/Pet.php |  5 ++++-
 docs/examples/specs/petstore/petstore-3.0.0.yaml      |  2 +-
 docs/examples/specs/petstore/petstore-3.1.0.yaml      |  2 +-
 docs/guide/faq.md                                     | 11 +++++++++++
 src/Annotations/AbstractAnnotation.php                |  2 +-
 src/Processors/DocBlockDescriptions.php               |  2 +-
 7 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/docs/examples/specs/petstore/annotations/Models/Pet.php b/docs/examples/specs/petstore/annotations/Models/Pet.php
index ce46e1c4b..57b8352c2 100644
--- a/docs/examples/specs/petstore/annotations/Models/Pet.php
+++ b/docs/examples/specs/petstore/annotations/Models/Pet.php
@@ -25,9 +25,11 @@
 class Pet
 {
     /**
+     * The description.
+     *
      * @OA\Property(
      *     format="int64",
-     *     description="ID",
+     *     description="",
      *     title="ID",
      * )
      *
diff --git a/docs/examples/specs/petstore/attributes/Models/Pet.php b/docs/examples/specs/petstore/attributes/Models/Pet.php
index ce9854bac..0d0064395 100644
--- a/docs/examples/specs/petstore/attributes/Models/Pet.php
+++ b/docs/examples/specs/petstore/attributes/Models/Pet.php
@@ -26,8 +26,11 @@
 )]
 class Pet
 {
+    /**
+     * The description.
+     */
     #[OAT\Property(
-        description: 'ID',
+        description: '',
         title: 'ID',
         format: 'int64'
     )]
diff --git a/docs/examples/specs/petstore/petstore-3.0.0.yaml b/docs/examples/specs/petstore/petstore-3.0.0.yaml
index 475aad438..ea0c660d2 100644
--- a/docs/examples/specs/petstore/petstore-3.0.0.yaml
+++ b/docs/examples/specs/petstore/petstore-3.0.0.yaml
@@ -592,7 +592,7 @@ components:
       properties:
         id:
           title: ID
-          description: ID
+          description: ''
           type: integer
           format: int64
         category:
diff --git a/docs/examples/specs/petstore/petstore-3.1.0.yaml b/docs/examples/specs/petstore/petstore-3.1.0.yaml
index 7c5fe0b15..8f8e8c73e 100644
--- a/docs/examples/specs/petstore/petstore-3.1.0.yaml
+++ b/docs/examples/specs/petstore/petstore-3.1.0.yaml
@@ -592,7 +592,7 @@ components:
       properties:
         id:
           title: ID
-          description: ID
+          description: ''
           type: integer
           format: int64
         category:
diff --git a/docs/guide/faq.md b/docs/guide/faq.md
index 5d07345fd..9e27ff6ac 100644
--- a/docs/guide/faq.md
+++ b/docs/guide/faq.md
@@ -174,3 +174,14 @@ The reason for this is that `openapi` currently uses the [`error_log`](https://w
 function for all output.
 
 So if this is configured to write to a file, then it will seem like the command is broken.
+
+## How to force overriding `swagger-php` augmentation
+
+There are number of processors that will try to 'enhance' the generated spec by adding additional details.
+
+This can be looking at PHP typehints, PHP docblocks for summary/description and other things. Usually this is fine; however,
+there might be times, where this is not desirable.
+
+For `string` based properties, the empty string `''` can be used to force ommission of a property, even if a `swagger-php` processor
+would have found a way to add a default value to this property.
+This can be useful, for example, for summary and description fields.
diff --git a/src/Annotations/AbstractAnnotation.php b/src/Annotations/AbstractAnnotation.php
index 34480c68e..e1ba09dd0 100644
--- a/src/Annotations/AbstractAnnotation.php
+++ b/src/Annotations/AbstractAnnotation.php
@@ -298,7 +298,7 @@ public function jsonSerialize()
 
         // Strip undefined values.
         foreach (get_object_vars($this) as $property => $value) {
-            if (!Generator::isDefault($value)) {
+            if (!Generator::isDefault($value) || '' === $value) {
                 $data->{$property} = $value;
             }
         }
diff --git a/src/Processors/DocBlockDescriptions.php b/src/Processors/DocBlockDescriptions.php
index a4cdaee4b..2c91c0b60 100644
--- a/src/Processors/DocBlockDescriptions.php
+++ b/src/Processors/DocBlockDescriptions.php
@@ -14,7 +14,7 @@
  * Checks if the annotation has a summary and/or description property
  * and uses the text in the comment block (above the annotations) as summary and/or description.
  *
- * Use <code>null</code>, for example: <code>@Annotation(description=null)</code>, if you don't want the annotation to have a description.
+ * Use <code>''</code>, for example: <code>@Annotation(description="")</code>, if you don't want the annotation to have a description.
  */
 class DocBlockDescriptions
 {