Add filters support for Swagger

Author: dunglas

features/swagger/doc.feature

@@ -51,10 +51,14 @@ Feature: Documentation support
     And the Swagger path "/api/custom-call/{id}" exists
     And the JSON node "paths./api/custom-call/{id}.get" should exist
     And the JSON node "paths./api/custom-call/{id}.put" should exist
-
     # Properties
     And "id" property exists for the Swagger class "Dummy"
     And "name" property is required for Swagger class "Dummy"
+    # Filters
+    And the JSON node "paths./dummies.get.parameters[0].name" should be equal to "id"
+    And the JSON node "paths./dummies.get.parameters[0].in" should be equal to "query"
+    And the JSON node "paths./dummies.get.parameters[0].required" should be false
+    And the JSON node "paths./dummies.get.parameters[0].type" should be equal to "integer"
 
   Scenario: Swagger UI is enabled for the doc endpoint
     Given I add "Accept" header equal to "text/html"

src/Bridge/Symfony/Bundle/Resources/config/swagger.xml

@@ -14,6 +14,7 @@
             <argument type="service" id="api_platform.operation_method_resolver" />
             <argument type="service" id="api_platform.operation_path_resolver" />
             <argument type="service" id="api_platform.router" />
+            <argument type="service" id="api_platform.filters" />
 
             <tag name="serializer.normalizer" priority="16" />
         </service>

src/Hydra/Serializer/CollectionFiltersNormalizer.php

@@ -63,7 +63,6 @@ public function normalize($object, $format = null, array $context = [])
         $resourceMetadata = $this->resourceMetadataFactory->create($resourceClass);
 
         $operationName = $context['collection_operation_name'] ?? null;
-
         if (null === $operationName) {
             $resourceFilters = $resourceMetadata->getAttribute('filters', []);
         } else {

src/Swagger/Serializer/DocumentationNormalizer.php

@@ -11,6 +11,7 @@
 
 namespace ApiPlatform\Core\Swagger\Serializer;
 
+use ApiPlatform\Core\Api\FilterCollection;
 use ApiPlatform\Core\Api\OperationMethodResolverInterface;
 use ApiPlatform\Core\Api\ResourceClassResolverInterface;
 use ApiPlatform\Core\Api\UrlGeneratorInterface;
@@ -43,8 +44,9 @@ final class DocumentationNormalizer implements NormalizerInterface
     private $operationMethodResolver;
     private $operationPathResolver;
     private $urlGenerator;
+    private $filterCollection;
 
-    public function __construct(ResourceMetadataFactoryInterface $resourceMetadataFactory, PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, PropertyMetadataFactoryInterface $propertyMetadataFactory, ResourceClassResolverInterface $resourceClassResolver, OperationMethodResolverInterface $operationMethodResolver, OperationPathResolverInterface $operationPathResolver, UrlGeneratorInterface $urlGenerator)
+    public function __construct(ResourceMetadataFactoryInterface $resourceMetadataFactory, PropertyNameCollectionFactoryInterface $propertyNameCollectionFactory, PropertyMetadataFactoryInterface $propertyMetadataFactory, ResourceClassResolverInterface $resourceClassResolver, OperationMethodResolverInterface $operationMethodResolver, OperationPathResolverInterface $operationPathResolver, UrlGeneratorInterface $urlGenerator, FilterCollection $filterCollection = null)
     {
         $this->resourceMetadataFactory = $resourceMetadataFactory;
         $this->propertyNameCollectionFactory = $propertyNameCollectionFactory;
@@ -53,6 +55,7 @@ public function __construct(ResourceMetadataFactoryInterface $resourceMetadataFa
         $this->operationMethodResolver = $operationMethodResolver;
         $this->operationPathResolver = $operationPathResolver;
         $this->urlGenerator = $urlGenerator;
+        $this->filterCollection = $filterCollection;
     }
 
     /**
@@ -196,6 +199,10 @@ private function updateGetOperation(\ArrayObject $pathOperation, array $mimeType
                 ],
             ];
 
+            if (!isset($pathOperation['parameters']) && count($parameters = $this->getFiltersParameters($resourceClass, $operationName, $resourceMetadata)) > 0) {
+                $pathOperation['parameters'] = $parameters;
+            }
+
             return $pathOperation;
         }
 
@@ -421,7 +428,6 @@ private function getPropertySchema(PropertyMetadata $propertyMetadata) : \ArrayO
      * Gets the Swagger's type corresponding to the given PHP's type.
      *
      * @param string $type
-     *
      * @param bool   $isCollection
      * @param string $className
      * @param bool   $readableLink
@@ -503,22 +509,45 @@ private function computeDoc(Documentation $documentation, \ArrayObject $definiti
         return $doc;
     }
 
+    /**
+     * Gets Swagger parameters corresponding to enabled filters.
+     *
+     * @param string           $resourceClass
+     * @param string           $operationName
+     * @param ResourceMetadata $resourceMetadata
+     *
+     * @return array
+     */
     private function getFiltersParameters(string $resourceClass, string $operationName, ResourceMetadata $resourceMetadata) : array
     {
-        $parameters = new \ArrayObject();
-        foreach($resourceMetadata->getCollectionOperationAttribute($operationName, 'filters', [], true) as $filter) {
-            foreach ($filter->getDescription($resourceClass) as $variable => $data) {
+        if (null === $this->filterCollection) {
+            return [];
+        }
+
+        $parameters = [];
+        $resourceFilters = $resourceMetadata->getCollectionOperationAttribute($operationName, 'filters', [], true);
+        foreach ($this->filterCollection as $filterName => $filter) {
+            if (!in_array($filterName, $resourceFilters)) {
+                continue;
+            }
+
+            foreach ($filter->getDescription($resourceClass) as $name => $data) {
                 $parameter = [
-                    'name' => $variable,
+                    'name' => $name,
                     'in' => 'query',
                     'required' => $data['required'],
-                    'type' => $this->getType($data['type'])
                 ];
+                $parameter += $this->getType($data['type'], false);
+
+                if (isset($data['swagger'])) {
+                    $parameter = $data['swagger'] + $parameter;
+                }
 
-                $data['swagger'] ?? $parameter = $data['swagger'] + $parameter;
                 $parameters[] = $parameter;
             }
         }
+
+        return $parameters;
     }
 
     /**

tests/Fixtures/DummyFilter.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace ApiPlatform\Core\Tests\Fixtures;
+
+use ApiPlatform\Core\Api\FilterInterface;
+
+/**
+ * @author Kévin Dunglas <[email protected]>
+ */
+class DummyFilter implements FilterInterface
+{
+    private $description;
+
+    public function __construct(array $description)
+    {
+        $this->description = $description;
+    }
+
+    /**
+     * Gets the description of this filter for the given resource.
+     *
+     * Returns an array with the filter parameter names as keys and array with the following data as values:
+     *   - property: the property where the filter is applied
+     *   - type: the type of the filter
+     *   - required: if this filter is required
+     *   - strategy: the used strategy
+     * The description can contain additional data specific to a filter.
+     *
+     * @param string $resourceClass
+     *
+     * @return array
+     */
+    public function getDescription(string $resourceClass) : array
+    {
+        return $this->description;
+    }
+}