Add deprecation support for Hydra (#1977)

* Add deprecation support for Hydra

* Deprecate the class too

Author: dunglas

features/bootstrap/HydraContext.php

@@ -70,6 +70,14 @@ public function assertTheHydraClassNotExist(string $className)
         throw new ExpectationFailedException(sprintf('The class "%s" exists.', $className));
     }
 
+    /**
+     * @Then the boolean value of the node :node of the Hydra class :class is true
+     */
+    public function assertBooleanNodeValueIs(string $nodeName, string $className)
+    {
+        Assert::assertTrue($this->propertyAccessor->getValue($this->getClassInfo($className), $nodeName));
+    }
+
     /**
      * @Then the value of the node :node of the Hydra class :class is :value
      */
@@ -81,6 +89,14 @@ public function assertNodeValueIs(string $nodeName, string $className, string $v
         );
     }
 
+    /**
+     * @Then the boolean value of the node :node of the property :prop of the Hydra class :class is true
+     */
+    public function assertPropertyNodeValueIsTrue(string $nodeName, string $propertyName, string $className)
+    {
+        Assert::assertTrue($this->propertyAccessor->getValue($this->getPropertyInfo($propertyName, $className), $nodeName));
+    }
+
     /**
      * @Then the value of the node :node of the property :prop of the Hydra class :class is :value
      */
@@ -92,6 +108,14 @@ public function assertPropertyNodeValueIs(string $nodeName, string $propertyName
         );
     }
 
+    /**
+     * @Then the boolean value of the node :node of the operation :operation of the Hydra class :class is true
+     */
+    public function assertOperationNodeBooleanValueIs(string $nodeName, string $operationMethod, string $className)
+    {
+        Assert::assertTrue($this->propertyAccessor->getValue($this->getOperation($operationMethod, $className), $nodeName));
+    }
+
     /**
      * @Then the value of the node :node of the operation :operation of the Hydra class :class is :value
      */

features/hydra/docs.feature

@@ -83,3 +83,8 @@ Feature: Documentation support
     And the value of the node "hydra:title" of the operation "PUT" of the Hydra class "Dummy" is "Replaces the Dummy resource."
     And the value of the node "hydra:title" of the operation "DELETE" of the Hydra class "Dummy" is "Deletes the Dummy resource."
     And the value of the node "returns" of the operation "DELETE" of the Hydra class "Dummy" is "owl:Nothing"
+    # Deprecations
+    And the boolean value of the node "owl:deprecated" of the Hydra class "DeprecatedResource" is true
+    And the boolean value of the node "owl:deprecated" of the property "deprecatedField" of the Hydra class "DeprecatedResource" is true
+    And the boolean value of the node "owl:deprecated" of the property "The collection of DeprecatedResource resources" of the Hydra class "The API entrypoint" is true
+    And the boolean value of the node "owl:deprecated" of the operation "GET" of the Hydra class "DeprecatedResource" is true

src/Hydra/Serializer/DocumentationNormalizer.php

@@ -97,7 +97,7 @@ private function populateEntrypointProperties(string $resourceClass, ResourceMet
             return;
         }
 
-        $entrypointProperties[] = [
+        $entrypointProperty = [
             '@type' => 'hydra:SupportedProperty',
             'hydra:property' => [
                 '@id' => sprintf('#Entrypoint/%s', lcfirst($shortName)),
@@ -119,6 +119,12 @@ private function populateEntrypointProperties(string $resourceClass, ResourceMet
             'hydra:readable' => true,
             'hydra:writable' => false,
         ];
+
+        if ($resourceMetadata->getCollectionOperationAttribute('GET', 'deprecation_reason', null, true)) {
+            $entrypointProperty['owl:deprecated'] = true;
+        }
+
+        $entrypointProperties[] = $entrypointProperty;
     }
 
     /**
@@ -146,6 +152,10 @@ private function getClass(string $resourceClass, ResourceMetadata $resourceMetad
             $class['hydra:description'] = $description;
         }
 
+        if ($resourceMetadata->getAttribute('deprecation_reason')) {
+            $class['owl:deprecated'] = true;
+        }
+
         return $class;
     }
 
@@ -263,6 +273,10 @@ private function getHydraOperation(string $resourceClass, ResourceMetadata $reso
         }
 
         $hydraOperation = $operation['hydra_context'] ?? [];
+        if ($resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'deprecation_reason', null, true)) {
+            $hydraOperation['owl:deprecated'] = true;
+        }
+
         $shortName = $resourceMetadata->getShortName();
 
         if ('GET' === $method && OperationType::COLLECTION === $operationType) {
@@ -504,6 +518,10 @@ private function getProperty(PropertyMetadata $propertyMetadata, string $propert
             $property['hydra:description'] = $description;
         }
 
+        if ($propertyMetadata->getAttribute('deprecation_reason')) {
+            $property['owl:deprecated'] = true;
+        }
+
         return $property;
     }