feat: add Swagger UI service to docker-compose and update OpenAPI annotations in controllers

docker-compose.yml

@@ -37,6 +37,20 @@ services:
     environment:
       PHP_IDE_CONFIG: serverName=localhost
 
+  swagger-ui:
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.swagger-ui.entrypoints=web-secure"
+      - "traefik.http.routers.swagger-ui.rule=Host(`localhost`) && PathPrefix(`/docs`)"
+      - "traefik.http.routers.swagger-ui.tls=true"
+      - "traefik.http.routers.swagger-ui.service=swagger-ui"
+      - "traefik.http.services.swagger-ui.loadbalancer.server.port=8080"
+    image: swaggerapi/swagger-ui:latest
+    container_name: swagger-ui
+    environment:
+      BASE_URL: /docs
+      URL: /.well-known/swagger.yaml
+
   migration-container:
     volumes:
       - ./db/migrations:/app/db/migrations

src/Controllers/HealthcheckController.php

@@ -23,9 +23,11 @@ use OpenApi\Attributes as OA;
 class HealthcheckController extends Controller
 {
     /**
+     * Handles the GET request for health check.
+     *
      * @throws \JsonException
      */
-    #[OA\Get(path: '/healthz')]
+    #[OA\Get(path: '/healthz', tags: ['Healthcheck'])]
     #[OA\Response(response: '200', description: 'Healthcheck OK')]
     #[OA\Response(response: '503', description: 'Healthcheck Failed')]
     public function get(ServerRequest $request): ResponseInterface

src/Controllers/IndexController.php

@@ -25,7 +25,7 @@ class IndexController extends Controller
     #[Guards\Jwt]
     #[Guards\Scope(['get.index', 'status.check'])]
     #[Guards\RequireAllScopes]
-    #[OA\Get(path: '/')]
+    #[OA\Get(path: '/', tags: ['Examples'])]
     #[OA\Response(
         response: '200',
         description: 'An Example Response',
@@ -40,11 +40,13 @@ class IndexController extends Controller
     }
 
     /**
+     * Handles the POST request for the index route.
+     *
      * @throws \JsonException
      */
     #[Guards\Jwt]
     #[Guards\Scope(['post.index'])]
-    #[OA\Post(path: '/')]
+    #[OA\Post(path: '/', tags: ['Examples'])]
     #[OA\Response(
         response: '200',
         description: 'An Example Response',