diff --git a/src/Analysis.php b/src/Analysis.php index 396113011..ff8465977 100644 --- a/src/Analysis.php +++ b/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(), ]; diff --git a/src/Context.php b/src/Context.php index e2dc6dec1..08b33fbc5 100644 --- a/src/Context.php +++ b/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; diff --git a/src/Processors/AugmentOperations.php b/src/Processors/AugmentOperations.php new file mode 100644 index 000000000..62bf37f28 --- /dev/null +++ b/src/Processors/AugmentOperations.php @@ -0,0 +1,48 @@ +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); + } +} diff --git a/tests/AugmentOperationTest.php b/tests/AugmentOperationTest.php new file mode 100644 index 000000000..d57d9604f --- /dev/null +++ b/tests/AugmentOperationTest.php @@ -0,0 +1,23 @@ +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'); + } +} diff --git a/tests/Fixtures/UsingPhpDoc.php b/tests/Fixtures/UsingPhpDoc.php new file mode 100644 index 000000000..329188218 --- /dev/null +++ b/tests/Fixtures/UsingPhpDoc.php @@ -0,0 +1,29 @@ + ['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'); } }