Merge pull request #1976 from dunglas/swagger-deprecated

Add deprecation support in Swagger

Author: dunglas

features/swagger/docs.feature

@@ -78,6 +78,15 @@ Feature: Documentation support
     # Subcollection - check schema
     And the JSON node "paths./related_dummies/{id}/related_to_dummy_friends.get.responses.200.schema.items.$ref" should be equal to "#/definitions/RelatedToDummyFriend-fakemanytomany"
 
+    # Deprecations
+    And the JSON node "paths./dummies.get.deprecated" should not exist
+    And the JSON node "paths./deprecated_resources.get.deprecated" should be true
+    And the JSON node "paths./deprecated_resources.post.deprecated" should be true
+    And the JSON node "paths./deprecated_resources/{id}.get.deprecated" should be true
+    And the JSON node "paths./deprecated_resources/{id}.delete.deprecated" should be true
+    And the JSON node "paths./deprecated_resources/{id}.put.deprecated" should be true
+    And the JSON node "paths./deprecated_resources/{id}.patch.deprecated" should be true
+
   Scenario: Swagger UI is enabled for docs endpoint
     Given I add "Accept" header equal to "text/html"
     And I send a "GET" request to "/docs"

src/Metadata/Resource/ResourceMetadata.php

@@ -13,6 +13,8 @@
 
 namespace ApiPlatform\Core\Metadata\Resource;
 
+use ApiPlatform\Core\Api\OperationType;
+
 /**
  * Resource metadata.
  *
@@ -263,6 +265,25 @@ public function getOperationAttribute(array $attributes, string $key, $defaultVa
         return $defaultValue;
     }
 
+    /**
+     * Gets an attribute for a given operation type and operation name.
+     *
+     * @param mixed $defaultValue
+     *
+     * @return mixed
+     */
+    public function getTypedOperationAttribute(string $operationType, string $operationName, string $key, $defaultValue = null, bool $resourceFallback = false)
+    {
+        switch ($operationType) {
+            case OperationType::COLLECTION:
+                return $this->getCollectionOperationAttribute($operationName, $key, $defaultValue, $resourceFallback);
+            case OperationType::ITEM:
+                return $this->getItemOperationAttribute($operationName, $key, $defaultValue, $resourceFallback);
+            default:
+                return $this->getSubresourceOperationAttribute($operationName, $key, $defaultValue, $resourceFallback);
+        }
+    }
+
     /**
      * Gets attributes.
      *

src/Swagger/Serializer/DocumentationNormalizer.php

@@ -244,6 +244,9 @@ private function getPathOperation(string $operationName, array $operation, strin
         $resourceShortName = $resourceMetadata->getShortName();
         $pathOperation['tags'] ?? $pathOperation['tags'] = [$resourceShortName];
         $pathOperation['operationId'] ?? $pathOperation['operationId'] = lcfirst($operationName).ucfirst($resourceShortName).ucfirst($operationType);
+        if ($resourceMetadata->getTypedOperationAttribute($operationType, $operationName, 'deprecation_reason', null, true)) {
+            $pathOperation['deprecated'] = true;
+        }
 
         switch ($method) {
             case 'GET':

tests/Metadata/Resource/ResourceMetadataTest.php

@@ -13,6 +13,7 @@
 
 namespace ApiPlatform\Core\Tests\Metadata\Resource;
 
+use ApiPlatform\Core\Api\OperationType;
 use ApiPlatform\Core\Metadata\Resource\ResourceMetadata;
 use PHPUnit\Framework\TestCase;
 
@@ -29,12 +30,14 @@ public function testValueObject()
         $this->assertSame('http://example.com/foo', $metadata->getIri());
         $this->assertSame(['iop1' => ['foo' => 'a'], 'iop2' => ['bar' => 'b']], $metadata->getItemOperations());
         $this->assertSame('a', $metadata->getItemOperationAttribute('iop1', 'foo', 'z', false));
+        $this->assertSame('a', $metadata->getTypedOperationAttribute(OperationType::ITEM, 'iop1', 'foo', 'z', false));
         $this->assertSame('bar', $metadata->getItemOperationAttribute('iop1', 'baz', 'z', true));
         $this->assertSame('bar', $metadata->getItemOperationAttribute(null, 'baz', 'z', true));
         $this->assertSame('z', $metadata->getItemOperationAttribute('iop1', 'notExist', 'z', true));
         $this->assertSame('z', $metadata->getItemOperationAttribute('notExist', 'notExist', 'z', true));
         $this->assertSame(['cop1' => ['foo' => 'c'], 'cop2' => ['bar' => 'd']], $metadata->getCollectionOperations());
         $this->assertSame('c', $metadata->getCollectionOperationAttribute('cop1', 'foo', 'z', false));
+        $this->assertSame('c', $metadata->getTypedOperationAttribute(OperationType::COLLECTION, 'cop1', 'foo', 'z', false));
         $this->assertSame('bar', $metadata->getCollectionOperationAttribute('cop1', 'baz', 'z', true));
         $this->assertSame('bar', $metadata->getCollectionOperationAttribute(null, 'baz', 'z', true));
         $this->assertSame('z', $metadata->getCollectionOperationAttribute('cop1', 'notExist', 'z', true));
@@ -44,6 +47,7 @@ public function testValueObject()
         $this->assertSame('z', $metadata->getAttribute('notExist', 'z'));
         $this->assertSame(['sop1' => ['sub' => 'bus']], $metadata->getSubresourceOperations());
         $this->assertSame('bus', $metadata->getSubresourceOperationAttribute('sop1', 'sub'));
+        $this->assertSame('bus', $metadata->getTypedOperationAttribute(OperationType::SUBRESOURCE, 'sop1', 'sub'));
         $this->assertSame('sub', $metadata->getSubresourceOperationAttribute('sop1', 'bus', 'sub', false));
         $this->assertSame('bar', $metadata->getSubresourceOperationAttribute('sop1', 'baz', 'sub', true));
         $this->assertSame('graphql', $metadata->getGraphqlAttribute('query', 'foo'));