Merge pull request #2391 from Toflar/propertyfilter-swagger-docs

Added swagger description to property filter

Author: dunglas

src/Serializer/Filter/PropertyFilter.php

@@ -67,12 +67,26 @@ public function apply(Request $request, bool $normalization, array $attributes,
      */
     public function getDescription(string $resourceClass): array
     {
+        $swaggerExample = sprintf('%s[]={propertyName}&%s[]={anotherPropertyName}&%s[{nestedPropertyParent}][]={nestedProperty}',
+            $this->parameterName,
+            $this->parameterName,
+            $this->parameterName
+        );
+
         return [
             "$this->parameterName[]" => [
                 'property' => null,
                 'type' => 'string',
                 'is_collection' => true,
                 'required' => false,
+                'swagger' => [
+                    'description' => 'Allows you to reduce the response to contain only the properties you need. If your desired property is nested, you can address it using nested arrays. Example: '.$swaggerExample,
+                    'name' => $this->parameterName,
+                    'type' => 'array',
+                    'items' => [
+                        'type' => 'string',
+                    ],
+                ],
             ],
         ];
     }

tests/Serializer/Filter/PropertyFilterTest.php

@@ -130,6 +130,14 @@ public function testGetDescription()
                 'type' => 'string',
                 'is_collection' => true,
                 'required' => false,
+                'swagger' => [
+                    'description' => 'Allows you to reduce the response to contain only the properties you need. If your desired property is nested, you can address it using nested arrays. Example: custom_properties[]={propertyName}&custom_properties[]={anotherPropertyName}&custom_properties[{nestedPropertyParent}][]={nestedProperty}',
+                    'name' => 'custom_properties',
+                    'type' => 'array',
+                    'items' => [
+                        'type' => 'string',
+                    ],
+                ],
             ],
         ];