From 5320aff7ad96e5909b2ec5fcaf0e867954d4505d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20=C3=96hlinger?= Date: Tue, 21 Apr 2020 13:40:13 +0200 Subject: [PATCH 1/3] added tags --- config/laravel-swagger.php | 16 ++++++++++++++- src/Generator.php | 23 ++++++++++++++++++---- src/SwaggerDocsManager.php | 1 + tests/GeneratorTest.php | 1 + tests/Stubs/Controllers/UserController.php | 3 +++ 5 files changed, 39 insertions(+), 5 deletions(-) diff --git a/config/laravel-swagger.php b/config/laravel-swagger.php index dbc6d71..c892344 100644 --- a/config/laravel-swagger.php +++ b/config/laravel-swagger.php @@ -45,7 +45,21 @@ /* |-------------------------------------------------------------------------- - | Parse summary and descriptions + | Generate tags from controller name + |-------------------------------------------------------------------------- + | + | If true creates a tag for an action from its controller name. + | (e.g. Methods in the UserController will be tagged with "User") + | This option does not overwrite any user specified tags on methods. + | Add "@tags tagName1 tagName2" to a methods phpDoc to use custom tags + | + */ + + 'autoTags' => false, + + /* + |-------------------------------------------------------------------------- + | Parse security |-------------------------------------------------------------------------- | | Tries to parse your middleware and defines the security definitions of diff --git a/src/Generator.php b/src/Generator.php index 81f998b..1f429ef 100644 --- a/src/Generator.php +++ b/src/Generator.php @@ -9,6 +9,7 @@ use Mtrajano\LaravelSwagger\Definitions\Security\Contracts\SecurityDefinitionsGenerator; use Mtrajano\LaravelSwagger\Definitions\Security\SecurityDefinitionsFactory; use Mtrajano\LaravelSwagger\Responses\ResponseGenerator; +use phpDocumentor\Reflection\DocBlock\Tags\Generic; use phpDocumentor\Reflection\DocBlockFactory; use ReflectionMethod; @@ -175,7 +176,12 @@ protected function generatePath(): void $actionInstance = $this->getActionClassInstance(); $docBlock = $actionInstance ? ($actionInstance->getDocComment() ?: '') : ''; - [$isDeprecated, $summary, $description] = $this->parseActionDocBlock($docBlock); + [$isDeprecated, $summary, $description, $tags] = $this->parseActionDocBlock($docBlock); + + if($this->config['autoTags'] && empty($tags)) { + $className = $actionInstance->getDeclaringClass()->getShortName(); + $tags = [substr($className, 0, strpos($className, 'Controller'))]; + } $path = $this->getRouteUri(); @@ -183,6 +189,7 @@ protected function generatePath(): void 'summary' => $summary, 'description' => $description, 'deprecated' => $isDeprecated, + 'tags' => $tags, ]; $this->addActionDefinitions(); @@ -283,7 +290,7 @@ private function getActionClassInstance(): ?ReflectionMethod private function parseActionDocBlock(string $docBlock): array { if (empty($docBlock) || !$this->config['parseDocBlock']) { - return [false, '', '']; + return [false, '', '', []]; } try { @@ -294,9 +301,17 @@ private function parseActionDocBlock(string $docBlock): array $summary = $parsedComment->getSummary(); $description = (string) $parsedComment->getDescription(); - return [$isDeprecated, $summary, $description]; + /** @var Generic $actionTag */ + $actionTag = collect($parsedComment->getTagsByName('tags'))->first(); + if($actionTag !== null && $actionTag->getDescription() !== null) { + $tags = explode(' ',$actionTag->getDescription()->getBodyTemplate()); + } else { + $tags = []; + } + + return [$isDeprecated, $summary, $description, $tags]; } catch (\Exception $e) { - return [false, '', '']; + return [false, '', '', []]; } } diff --git a/src/SwaggerDocsManager.php b/src/SwaggerDocsManager.php index bd208e3..be8de4c 100644 --- a/src/SwaggerDocsManager.php +++ b/src/SwaggerDocsManager.php @@ -158,6 +158,7 @@ private function _getFilledWithGlobalConfigs(array $version): array $version['description'] = $this->_config['description']; $version['schemes'] = $this->_config['schemes']; $version['parseDocBlock'] = $this->_config['parseDocBlock']; + $version['autoTags'] = $this->_config['autoTags']; $version['parseSecurity'] = $this->_config['parseSecurity']; $version['generateExampleData'] = $this->_config['generateExampleData']; $version['parseModelRelationships'] = $this->_config['parseModelRelationships']; diff --git a/tests/GeneratorTest.php b/tests/GeneratorTest.php index 3e8ebe4..8f28a65 100644 --- a/tests/GeneratorTest.php +++ b/tests/GeneratorTest.php @@ -291,6 +291,7 @@ public function testRouteData($paths) $this->assertEquals('', $paths['/users/{id}']['get']['summary']); $this->assertEquals(false, $paths['/users/{id}']['get']['deprecated']); $this->assertEquals('', $paths['/users/{id}']['get']['description']); + $this->assertEquals(['user', 'show'], $paths['/users/{id}']['get']['tags']); $this->assertEquals('', $paths['/users/details']['get']['summary']); $this->assertEquals(true, $paths['/users/details']['get']['deprecated']); diff --git a/tests/Stubs/Controllers/UserController.php b/tests/Stubs/Controllers/UserController.php index b50a407..361c827 100644 --- a/tests/Stubs/Controllers/UserController.php +++ b/tests/Stubs/Controllers/UserController.php @@ -14,6 +14,9 @@ public function index() return json_encode([['first_name' => 'John'], ['first_name' => 'Jack']]); } + /** + * @tags user show + */ public function show(UserShowRequest $request, $id) { return json_encode(['first_name' => 'John']); From b21903e8454fb82484358779ee6dcaeaff107d83 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20=C3=96hlinger?= Date: Tue, 21 Apr 2020 15:13:29 +0200 Subject: [PATCH 2/3] fixed failing tests by adding new autoTags config --- tests/Feature/SwaggerDocsTest.php | 1 + tests/SwaggerDocsManagerTest.php | 2 ++ 2 files changed, 3 insertions(+) diff --git a/tests/Feature/SwaggerDocsTest.php b/tests/Feature/SwaggerDocsTest.php index 6ac21f3..123714f 100644 --- a/tests/Feature/SwaggerDocsTest.php +++ b/tests/Feature/SwaggerDocsTest.php @@ -20,6 +20,7 @@ public function testGetSwaggerUiUsingDefaultVersion() 'host' => env('APP_URL'), 'schemes' => [], 'parseDocBlock' => true, + 'autoTags' => false, 'parseSecurity' => true, 'generateExampleData' => true, 'parseModelRelationships' => true, diff --git a/tests/SwaggerDocsManagerTest.php b/tests/SwaggerDocsManagerTest.php index 23094d3..d037f15 100644 --- a/tests/SwaggerDocsManagerTest.php +++ b/tests/SwaggerDocsManagerTest.php @@ -23,6 +23,7 @@ protected function setUp(): void 'description' => '', 'schemes' => [], 'parseDocBlock' => true, + 'autoTags' => false, 'parseSecurity' => true, 'generateExampleData' => true, 'parseModelRelationships' => true, @@ -68,6 +69,7 @@ protected function setUp(): void 'title' => '', 'description' => '', 'parseDocBlock' => true, + 'autoTags' => false, 'parseSecurity' => true, 'generateExampleData' => true, 'parseModelRelationships' => true, From 5e25c1274c8169d5d88cc7dec681c89c6a9d911b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20=C3=96hlinger?= Date: Tue, 21 Apr 2020 15:19:21 +0200 Subject: [PATCH 3/3] fixed code style issues --- src/Generator.php | 6 +++--- src/SwaggerDocsManager.php | 2 +- tests/SwaggerDocsManagerTest.php | 3 ++- 3 files changed, 6 insertions(+), 5 deletions(-) diff --git a/src/Generator.php b/src/Generator.php index 1f429ef..77f88d3 100644 --- a/src/Generator.php +++ b/src/Generator.php @@ -178,7 +178,7 @@ protected function generatePath(): void [$isDeprecated, $summary, $description, $tags] = $this->parseActionDocBlock($docBlock); - if($this->config['autoTags'] && empty($tags)) { + if ($this->config['autoTags'] && empty($tags)) { $className = $actionInstance->getDeclaringClass()->getShortName(); $tags = [substr($className, 0, strpos($className, 'Controller'))]; } @@ -303,8 +303,8 @@ private function parseActionDocBlock(string $docBlock): array /** @var Generic $actionTag */ $actionTag = collect($parsedComment->getTagsByName('tags'))->first(); - if($actionTag !== null && $actionTag->getDescription() !== null) { - $tags = explode(' ',$actionTag->getDescription()->getBodyTemplate()); + if ($actionTag !== null && $actionTag->getDescription() !== null) { + $tags = explode(' ', $actionTag->getDescription()->getBodyTemplate()); } else { $tags = []; } diff --git a/src/SwaggerDocsManager.php b/src/SwaggerDocsManager.php index be8de4c..8ebbb63 100644 --- a/src/SwaggerDocsManager.php +++ b/src/SwaggerDocsManager.php @@ -103,7 +103,7 @@ public function getSwaggerFileUrl(string $version): string $fileName = $this->generateSwaggerFileName($version, $format); - return sprintf("%s/%s", config('app.url'), $fileName); + return sprintf('%s/%s', config('app.url'), $fileName); } /** diff --git a/tests/SwaggerDocsManagerTest.php b/tests/SwaggerDocsManagerTest.php index d037f15..23cfad5 100644 --- a/tests/SwaggerDocsManagerTest.php +++ b/tests/SwaggerDocsManagerTest.php @@ -153,7 +153,8 @@ public function provideInvalidFileNames(): array /** * @dataProvider provideInvalidFileNames */ - public function testChangeFileNameGeneratorReturningInvalidFileName($invalidFileName): void { + public function testChangeFileNameGeneratorReturningInvalidFileName($invalidFileName): void + { $this->expectException(RuntimeException::class); SwaggerDocsManager::setFileNameGenerator(