Add augmentation for operations

src/Analysis.php

@@ -13,6 +13,7 @@
 use Swagger\Annotations\AbstractAnnotation;
 use Swagger\Annotations\Swagger;
 use Swagger\Processors\AugmentDefinitions;
+use Swagger\Processors\AugmentOperations;
 use Swagger\Processors\AugmentParameters;
 use Swagger\Processors\AugmentProperties;
 use Swagger\Processors\BuildPaths;
@@ -290,6 +291,7 @@ public static function &processors()
                 new AugmentDefinitions(),
                 new AugmentProperties(),
                 new InheritProperties(),
+                new AugmentOperations(),
                 new AugmentParameters(),
                 new CleanUnmerged(),
             ];

src/Context.php

@@ -63,7 +63,7 @@ public function is($type)
     {
         return property_exists($this, $type);
     }
-    
+
     /**
      * Check if a property is NOT set directly on this context and but its parent context.
      *
@@ -174,8 +174,13 @@ public function extractDescription()
             if (substr($line, 0, 1) === '@') {
                 break;
             }
-            $description .= $line . ' ';
+            if ($line === '') {
+                $description = trim($description) . "\n";
+            } else {
+                $description .= $line . ' ';
+            }
         }
+
         $description = trim($description);
         if ($description === '') {
             return null;

src/Processors/AugmentOperations.php

@@ -0,0 +1,48 @@
+<?php
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace Swagger\Processors;
+
+use Swagger\Context;
+use Swagger\Analysis;
+use Swagger\Annotations\Operation;
+
+/**
+ * Use the operation context to extract useful information and inject that into the annotation.
+ */
+class AugmentOperations
+{
+    public function __invoke(Analysis $analysis)
+    {
+        $allOperations = $analysis->getAnnotationsOfType('\Swagger\Annotations\Operation');
+
+        /** @var Operation $operation */
+        foreach ($allOperations as $operation) {
+            list($contextSummary, $contextDescription) = $this->splitDescription($operation->_context->extractDescription());
+
+            if (null === $operation->summary && $contextSummary) {
+                $operation->summary = $contextSummary;
+            }
+            if (null === $operation->description && $contextDescription) {
+                $operation->description = $contextDescription;
+            }
+        }
+    }
+
+    /**
+     * @param string $description
+     *
+     * @return string[]
+     */
+    private function splitDescription($description)
+    {
+        if (!$description || false === strpos($description, "\n")) {
+            return array($description, '');
+        }
+
+        return explode("\n", $description, 2);
+    }
+}

tests/AugmentOperationTest.php

@@ -0,0 +1,23 @@
+<?php
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace SwaggerTests;
+
+class AugmentOperationTest extends SwaggerTestCase
+{
+    public function testAugmentOperation()
+    {
+        $swagger = \Swagger\scan(__DIR__ . '/Fixtures/UsingPhpDoc.php');
+
+        $this->assertSame('api/test1', $swagger->paths[0]->path);
+        $this->assertSame('Example summary', $swagger->paths[0]->get->summary, 'Operation summary should be taken from phpDoc');
+        $this->assertSame('Example description... More description...', $swagger->paths[0]->get->description, 'Operation description should be taken from phpDoc');
+
+        $this->assertSame('api/test2', $swagger->paths[1]->path);
+        $this->assertSame('Example summary', $swagger->paths[1]->get->summary, 'Operation summary should be taken from phpDoc');
+        $this->assertNull($swagger->paths[1]->get->description, 'Operation description should be taken from phpDoc');
+    }
+}

tests/Fixtures/UsingPhpDoc.php

@@ -0,0 +1,29 @@
+<?php
+namespace SwaggerFixtures;
+
+/**
+ * @SWG\Info(title="Fixture for AugmentOperationTest", version="test")
+ */
+class UsingPhpDoc
+{
+    /**
+     * Example summary
+     *
+     * Example description...
+     * More description...
+     *
+     * @SWG\Get(path="api/test1", @SWG\Response(response="200", description="a response"))
+     */
+    public function methodWithDescription()
+    {
+    }
+
+    /**
+     * Example summary
+     *
+     * @SWG\Get(path="api/test2", @SWG\Response(response="200", description="a response"))
+     */
+    public function methodWithSummary()
+    {
+    }
+}

tests/UtilTest.php

@@ -13,7 +13,7 @@ class UtilTest extends SwaggerTestCase
 
     public function testExclude()
     {
-        $swagger = \Swagger\scan(__DIR__ . '/Fixtures', ['exclude' => ['Customer.php', 'UsingRefs.php', 'GrandParent.php']]);
+        $swagger = \Swagger\scan(__DIR__ . '/Fixtures', ['exclude' => ['Customer.php', 'UsingRefs.php', 'UsingPhpDoc.php', 'GrandParent.php']]);
         $this->assertSame('Fixture for ParserTest', $swagger->info->title, 'No errors about duplicate @SWG\Info() annotations');
     }
 }