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..77f88d3 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..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); } /** @@ -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/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/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']); diff --git a/tests/SwaggerDocsManagerTest.php b/tests/SwaggerDocsManagerTest.php index 23094d3..23cfad5 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, @@ -151,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(