feat(hydra): parameter documentation

Author: soyuka

src/Hydra/Serializer/CollectionFiltersNormalizer.php

@@ -18,6 +18,9 @@
 use ApiPlatform\Doctrine\Odm\State\Options as ODMOptions;
 use ApiPlatform\Doctrine\Orm\State\Options;
 use ApiPlatform\Metadata\FilterInterface;
+use ApiPlatform\Metadata\Parameter;
+use ApiPlatform\Metadata\Parameters;
+use ApiPlatform\Metadata\QueryParameterInterface;
 use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
 use ApiPlatform\Metadata\ResourceClassResolverInterface;
 use ApiPlatform\Serializer\CacheableSupportsMethodInterface;
@@ -97,8 +100,10 @@ public function normalize(mixed $object, ?string $format = null, array $context
         }
         $resourceClass = $this->resourceClassResolver->getResourceClass($object, $context['resource_class']);
         $operation = $context['operation'] ?? $this->resourceMetadataCollectionFactory->create($resourceClass)->getOperation($context['operation_name'] ?? null);
+
+        $parameters = $operation->getParameters();
         $resourceFilters = $operation->getFilters();
-        if (!$resourceFilters) {
+        if (!$resourceFilters && !$parameters) {
             return $data;
         }
 
@@ -123,8 +128,8 @@ public function normalize(mixed $object, ?string $format = null, array $context
             }
         }
 
-        if ($currentFilters) {
-            $data['hydra:search'] = $this->getSearch($resourceClass, $requestParts, $currentFilters);
+        if ($currentFilters || ($parameters && \count($parameters))) {
+            $data['hydra:search'] = $this->getSearch($resourceClass, $requestParts, $currentFilters, $parameters);
         }
 
         return $data;
@@ -144,8 +149,9 @@ public function setNormalizer(NormalizerInterface $normalizer): void
      * Returns the content of the Hydra search property.
      *
      * @param LegacyFilterInterface[]|FilterInterface[] $filters
+     * @param array<string, Parameter>                  $parameters
      */
-    private function getSearch(string $resourceClass, array $parts, array $filters): array
+    private function getSearch(string $resourceClass, array $parts, array $filters, array|Parameters|null $parameters): array
     {
         $variables = [];
         $mapping = [];
@@ -156,6 +162,45 @@ private function getSearch(string $resourceClass, array $parts, array $filters):
             }
         }
 
+        foreach ($parameters ?? [] as $key => $parameter) {
+            // Each IriTemplateMapping maps a variable used in the template to a property
+            if (!$parameter instanceof QueryParameterInterface) {
+                continue;
+            }
+
+            if (!($property = $parameter->getProperty()) && ($filterId = $parameter->getFilter()) && ($filter = $this->getFilter($filterId))) {
+                foreach ($filter->getDescription($resourceClass) as $variable => $description) {
+                    // This is a practice induced by PHP and is not necessary when implementing URI template
+                    if (str_ends_with((string) $variable, '[]')) {
+                        continue;
+                    }
+
+                    // :property is a pattern allowed when defining parameters
+                    $k = str_replace(':property', $description['property'], $key);
+                    $variable = str_replace($description['property'], $k, $variable);
+                    $variables[] = $variable;
+                    $m = ['@type' => 'IriTemplateMapping', 'variable' => $variable, 'property' => $description['property'], 'required' => $description['required']];
+                    if (null !== ($required = $parameter->getRequired())) {
+                        $m['required'] = $required;
+                    }
+                    $mapping[] = $m;
+                }
+
+                continue;
+            }
+
+            if (!$property) {
+                continue;
+            }
+
+            $m = ['@type' => 'IriTemplateMapping', 'variable' => $key, 'property' => $property];
+            $variables[] = $key;
+            if (null !== ($required = $parameter->getRequired())) {
+                $m['required'] = $required;
+            }
+            $mapping[] = $m;
+        }
+
         return ['@type' => 'hydra:IriTemplate', 'hydra:template' => sprintf('%s{?%s}', $parts['path'], implode(',', $variables)), 'hydra:variableRepresentation' => 'BasicRepresentation', 'hydra:mapping' => $mapping];
     }