Replace @GroupPath() with @path() annotation

The constraint that @GroupPath can only be used on abstract classes is
no longer needed. The unambiguity is preserved by thanks to iterating
over the controller's ancestors separately.

.docs/endpoints.md

@@ -13,11 +13,10 @@ Create base controller with root path to your api
 ```php
 namespace App\Api\V1\Controllers;
 
-use Apitte\Core\Annotation\Controller\GroupPath;
 use Apitte\Core\UI\Controller\IController;
 
 /**
- * @GroupPath("/api/v1")
+ * @Path("/api/v1")
  */
 abstract class BaseV1Controller implements IController
 {
@@ -81,7 +80,7 @@ class UsersController extends BaseV1Controller
 }
 ```
 
-**Tip** Combination of `GroupPath("/")`, `@Path("/")` on a Controller and `@Path("/")` on a method targets homepage, e.q. `example.com/`.
+**Tip** Use the `@Path("/")` annotation on a Controller and its method to target the homepage, e.q. `example.com/`.
 
 ### List of annotations
 
@@ -95,17 +94,15 @@ ID
   - `@Id`
     - Defined on method
 
-Path
+`@Path`
   - See example controllers above
   - Must consist only of following characters: `a-z`, `A-Z`, `0-9`, `-_/`
-  - `@GroupPath`
-    - Abstract classes only
-    - Defined on controller
-  - `@Path`
-    - Defined on controller
-  - `@Path`
-    - Defined on method
-
+  - The `@Path` annotation can be used on:
+    - abstract controller to define a group path for multiple controllers (e.g. `example.com/v1/...`)
+    - final controller to define a path for that particular controller (e.g. `example.com/v1/users`)
+    - method to define a path for a specific endpoint
+  - This hierarchy is then used to build the schema and make routing possible.
+
 `@Method`
   - Allowed HTTP method for endpoint
   - GET, POST, PUT, OPTION, DELETE, HEAD

src/DI/Loader/DoctrineAnnotationLoader.php

@@ -4,7 +4,6 @@
 
 use Apitte\Core\Annotation\Controller\ControllerId;
 use Apitte\Core\Annotation\Controller\GroupId;
-use Apitte\Core\Annotation\Controller\GroupPath;
 use Apitte\Core\Annotation\Controller\Id;
 use Apitte\Core\Annotation\Controller\Method;
 use Apitte\Core\Annotation\Controller\Negotiations;
@@ -159,11 +158,6 @@ protected function parseControllerClassAnnotations(Controller $controller, Class
 			if (get_class($annotation) === GroupId::class) {
 				throw new InvalidStateException(sprintf('Annotation @GroupId cannot be on non-abstract "%s"', $class->getName()));
 			}
-
-			// Parse @GroupPath ============================
-			if (get_class($annotation) === GroupPath::class) {
-				throw new InvalidStateException(sprintf('Annotation @GroupPath cannot be on non-abstract "%s"', $class->getName()));
-			}
 		}
 
 		// Reverse order
@@ -182,9 +176,9 @@ protected function parseControllerClassAnnotations(Controller $controller, Class
 					$controller->addGroupId($annotation->getName());
 				}
 
-				// Parse @GroupPath ========================
-				if (get_class($annotation) === GroupPath::class) {
-					/** @var GroupPath $annotation */
+				// Parse @Path ========================
+				if (get_class($annotation) === Path::class) {
+					/** @var Path $annotation */
 					$controller->addGroupPath($annotation->getPath());
 				}
 

src/Schema/Serialization/ArraySerializator.php

@@ -59,7 +59,7 @@ private function serializeEndpoint(Controller $controller, Method $method): arra
 	 */
 	private function serializeInit(Controller $controller, Method $method): array
 	{
-		// Build full mask (@GroupPath(s) + Controller @Path + Endpoint @Path)
+		// Build full mask (Group @Path(s) + Controller @Path + Endpoint @Path)
 		// without duplicated slashes (//)
 		// and without trailing slash at the end
 		// but with slash at the beginning
@@ -156,7 +156,7 @@ private function serializePattern(array &$endpoint, Controller $controller, Meth
 					continue 2;
 				}
 			}
-			throw new InvalidStateException(sprintf('@RequestParameter(name="%s", in=path) is not defined in mask (in @GroupPath or @Path)', $parameter->getName()));
+			throw new InvalidStateException(sprintf('@RequestParameter(name="%s", in=path) is not defined in mask (@Path annotations)', $parameter->getName()));
 		}
 
 		// Fulfill endpoint parameters (in path)

src/Schema/Validation/GroupPathValidation.php

@@ -24,21 +24,21 @@ protected function validateSlashes(SchemaBuilder $builder): void
 				if ($groupPath === '/') {
 					// INVALID: nonsense
 					throw new InvalidSchemaException(
-						sprintf('@GroupPath "%s" in "%s" cannot be only "/", it is nonsense.', $groupPath, $controller->getClass())
+						sprintf('@Path "%s" in "%s" cannot be only "/", it is nonsense.', $groupPath, $controller->getClass())
 					);
 				}
 
 				// MUST: Starts with slash (/)
 				if (substr($groupPath, 0, 1) !== '/') {
 					throw new InvalidSchemaException(
-						sprintf('@GroupPath "%s" in "%s" must starts with "/" (slash).', $groupPath, $controller->getClass())
+						sprintf('@Path "%s" in "%s" must starts with "/" (slash).', $groupPath, $controller->getClass())
 					);
 				}
 
 				// MUST NOT: Ends with slash (/)
 				if (substr($groupPath, -1, 1) === '/') {
 					throw new InvalidSchemaException(
-						sprintf('@GroupPath "%s" in "%s" must not ends with "/" (slash).', $groupPath, $controller->getClass())
+						sprintf('@Path "%s" in "%s" must not ends with "/" (slash).', $groupPath, $controller->getClass())
 					);
 				}
 			}
@@ -63,7 +63,7 @@ protected function validateRegex(SchemaBuilder $builder): void
 				if ($match !== null) {
 					throw new InvalidSchemaException(
 						sprintf(
-							'@GroupPath "%s" in "%s" contains illegal characters "%s". Allowed characters are only [a-zA-Z0-9-_/].',
+							'@Path "%s" in "%s" contains illegal characters "%s". Allowed characters are only [a-zA-Z0-9-_/].',
 							$path,
 							$controller->getClass(),
 							$match[1]

tests/cases/DI/Loader/DoctrineAnnotationLoader.phpt

@@ -15,7 +15,6 @@ use Nette\DI\ServiceDefinition;
 use Tester\Assert;
 use Tests\Fixtures\Controllers\FoobarController;
 use Tests\Fixtures\Controllers\InvalidGroupAnnotationController;
-use Tests\Fixtures\Controllers\InvalidGroupPathAnnotationController;
 
 // Check if controller is found
 test(function (): void {
@@ -90,15 +89,3 @@ test(function (): void {
 		$loader->load(new SchemaBuilder());
 	}, InvalidStateException::class, sprintf('Annotation @GroupId cannot be on non-abstract "%s"', InvalidGroupAnnotationController::class));
 });
-
-// Invalid annotation (@GroupPath)
-test(function (): void {
-	Assert::exception(function (): void {
-		$builder = new ContainerBuilder();
-		$builder->addDefinition('invalid')
-			->setClass(InvalidGroupPathAnnotationController::class);
-
-		$loader = new DoctrineAnnotationLoader($builder);
-		$loader->load(new SchemaBuilder());
-	}, InvalidStateException::class, sprintf('Annotation @GroupPath cannot be on non-abstract "%s"', InvalidGroupPathAnnotationController::class));
-});

tests/cases/Schema/Serialization/ArraySerializator.phpt

@@ -210,5 +210,5 @@ test(function (): void {
 
 	Assert::exception(function () use ($serializator, $builder): void {
 		$serializator->serialize($builder);
-	}, InvalidStateException::class, '@RequestParameter(name="m1-p1", in=path) is not defined in mask (in @GroupPath or @Path)');
+	}, InvalidStateException::class, '@RequestParameter(name="m1-p1", in=path) is not defined in mask (@Path annotations)');
 });

tests/cases/Schema/Validation/GroupPathValidation.phpt

@@ -34,7 +34,7 @@ test(function (): void {
 
 	Assert::exception(function () use ($validation, $builder): void {
 		$validation->validate($builder);
-	}, InvalidSchemaException::class, '@GroupPath "/" in "c1" cannot be only "/", it is nonsense.');
+	}, InvalidSchemaException::class, '@Path "/" in "c1" cannot be only "/", it is nonsense.');
 });
 
 // Validate: starts with /
@@ -47,7 +47,7 @@ test(function (): void {
 
 	Assert::exception(function () use ($validation, $builder): void {
 		$validation->validate($builder);
-	}, InvalidSchemaException::class, '@GroupPath "foo" in "c1" must starts with "/" (slash).');
+	}, InvalidSchemaException::class, '@Path "foo" in "c1" must starts with "/" (slash).');
 });
 
 // Validate: end with /
@@ -60,7 +60,7 @@ test(function (): void {
 
 	Assert::exception(function () use ($validation, $builder): void {
 		$validation->validate($builder);
-	}, InvalidSchemaException::class, '@GroupPath "/foo/" in "c1" must not ends with "/" (slash).');
+	}, InvalidSchemaException::class, '@Path "/foo/" in "c1" must not ends with "/" (slash).');
 });
 
 // Validate: invalid characters
@@ -73,5 +73,5 @@ test(function (): void {
 
 	Assert::exception(function () use ($validation, $builder): void {
 		$validation->validate($builder);
-	}, InvalidSchemaException::class, '@GroupPath "/{foo$}" in "c1" contains illegal characters "{". Allowed characters are only [a-zA-Z0-9-_/].');
+	}, InvalidSchemaException::class, '@Path "/{foo$}" in "c1" contains illegal characters "{". Allowed characters are only [a-zA-Z0-9-_/].');
 });

tests/fixtures/Controllers/AbstractController.php

@@ -3,12 +3,12 @@
 namespace Tests\Fixtures\Controllers;
 
 use Apitte\Core\Annotation\Controller\GroupId;
-use Apitte\Core\Annotation\Controller\GroupPath;
+use Apitte\Core\Annotation\Controller\Path;
 use Apitte\Core\UI\Controller\IController;
 
 /**
  * @GroupId("testapi")
- * @GroupPath("/api")
+ * @Path("/api")
  */
 abstract class AbstractController implements IController
 {

tests/fixtures/Controllers/ApiV1Controller.php

@@ -2,10 +2,10 @@
 
 namespace Tests\Fixtures\Controllers;
 
-use Apitte\Core\Annotation\Controller\GroupPath;
+use Apitte\Core\Annotation\Controller\Path;
 
 /**
- * @GroupPath("/v1")
+ * @Path("/v1")
  */
 abstract class ApiV1Controller extends AbstractController
 {