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 null, for example: @Annotation(description=null), if you don't want the annotation to have a description.
+ * Use '', for example: @Annotation(description=""), if you don't want the annotation to have a description.
*/
class DocBlockDescriptions
{