Merge pull request #2406 from antograssiot/openapi-filter-description

Added OpenAPI description to property filter

Author: dunglas

src/Api/FilterInterface.php

@@ -35,6 +35,14 @@ interface FilterInterface
      *       'name' => 'My Name',
      *       'type' => 'integer',
      *     ]
+     *   - openapi (optional): additional parameters for the path operation in the version 3 spec,
+     *     e.g. 'openapi' => [
+     *       'description' => 'My Description',
+     *       'name' => 'My Name',
+     *       'schema' => [
+     *          'type' => 'integer',
+     *       ]
+     *     ]
      * The description can contain additional data specific to a filter.
      *
      * @see \ApiPlatform\Core\Swagger\Serializer\DocumentationNormalizer::getFiltersParameters

src/Serializer/Filter/PropertyFilter.php

@@ -67,9 +67,7 @@ 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,
+        $example = sprintf('%1$s[]={propertyName}&%1$s[]={anotherPropertyName}&%1$s[{nestedPropertyParent}][]={nestedProperty}',
             $this->parameterName
         );
 
@@ -80,13 +78,23 @@ public function getDescription(string $resourceClass): array
                 '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,
+                    '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: '.$example,
                     'name' => $this->parameterName,
                     'type' => 'array',
                     'items' => [
                         'type' => 'string',
                     ],
                 ],
+                'openapi' => [
+                    '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: '.$example,
+                    'name' => $this->parameterName,
+                    'schema' => [
+                        'type' => 'array',
+                        'items' => [
+                            'type' => 'string',
+                        ],
+                    ],
+                ],
             ],
         ];
     }

tests/Serializer/Filter/PropertyFilterTest.php

@@ -138,6 +138,16 @@ public function testGetDescription()
                         'type' => 'string',
                     ],
                 ],
+                'openapi' => [
+                    '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',
+                    'schema' => [
+                        'type' => 'array',
+                        'items' => [
+                            'type' => 'string',
+                        ],
+                    ],
+                ],
             ],
         ];