✨ **Enhance API functionality and localizations**

- 🌐 Added API documentation annotations for multiple controllers (Meetups, Cities, Countries, Courses, Highscores, Venues), improving public and developer-facing endpoint clarity.
- ➕ Integrated and configured the `dedoc/scramble` package for automated OpenAPI documentation generation.
- 🔒 Excluded internal routes and actions from API documentation using `ExcludeRouteFromDocs` attributes.
- 🌍 Added new localization keys for API Token features across multiple languages (`lv`, `es`, etc.).
- 🛠️ Introduced `Group`, `Response`, and `QueryParameter` attributes for better request descriptions and structured documentation.
- 🚀 Enhanced functionality for listing operations in controllers with filters and query parameters like `search` and `selected`.

app/Http/Controllers/Api/VenueController.php

@@ -5,15 +5,24 @@ namespace App\Http\Controllers\Api;
 use App\Http\Controllers\Controller;
 use App\Models\Lecturer;
 use App\Models\Venue;
+use Dedoc\Scramble\Attributes\ExcludeRouteFromDocs;
+use Dedoc\Scramble\Attributes\Group;
+use Dedoc\Scramble\Attributes\QueryParameter;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Http\Request;
 
+#[Group(name: 'Stammdaten', weight: 5)]
 class VenueController extends Controller
 {
     /**
-     * Display a listing of the resource.
-     * @return \Illuminate\Http\Response
+     * Veranstaltungsorte auflisten und durchsuchen
+     *
+     * Öffentlicher Endpunkt; liefert id, name und die zugehörige Stadt/Land, alphabetisch sortiert.
+     * Ohne 'selected' wird die Liste auf 10 Einträge begrenzt. Jeder Ort enthält zusätzlich
+     * 'flag' (SVG-URL der Landesflagge) und 'description' (Stadt + Straße).
      */
+    #[QueryParameter(name: 'search', description: 'Teilstring-Suche im Namen des Veranstaltungsortes.', required: false, type: 'string')]
+    #[QueryParameter(name: 'selected', description: 'Lädt gezielt die angegebenen Veranstaltungsort-IDs (umgeht die Begrenzung auf 10 Einträge).', required: false, type: 'array')]
     public function index(Request $request)
     {
         return Venue::query()
@@ -22,19 +31,19 @@ class VenueController extends Controller
             ->orderBy('name')
             ->when(
                 $request->search,
-                fn(Builder $query) => $query
+                fn (Builder $query) => $query
                     ->where('name', 'ilike', "%{$request->search}%")
             )
             ->when(
                 $request->exists('selected'),
-                fn(Builder $query) => $query->whereIn('id',
+                fn (Builder $query) => $query->whereIn('id',
                     $request->input('selected', [])),
-                fn(Builder $query) => $query->limit(10)
+                fn (Builder $query) => $query->limit(10)
             )
             ->get()
             ->map(function (Venue $venue) {
-                $venue->flag = asset('vendor/blade-country-flags/4x3-' . $venue->city->country->code . '.svg');
-                $venue->description = $venue->city->name . ', ' . $venue->street;
+                $venue->flag = asset('vendor/blade-country-flags/4x3-'.$venue->city->country->code.'.svg');
+                $venue->description = $venue->city->name.', '.$venue->street;
 
                 return $venue;
             });
@@ -42,8 +51,8 @@ class VenueController extends Controller
 
     /**
      * Store a newly created resource in storage.
-     * @return \Illuminate\Http\Response
      */
+    #[ExcludeRouteFromDocs]
     public function store(Request $request)
     {
         //
@@ -51,8 +60,8 @@ class VenueController extends Controller
 
     /**
      * Display the specified resource.
-     * @return \Illuminate\Http\Response
      */
+    #[ExcludeRouteFromDocs]
     public function show(Lecturer $lecturer)
     {
         //
@@ -60,8 +69,8 @@ class VenueController extends Controller
 
     /**
      * Update the specified resource in storage.
-     * @return \Illuminate\Http\Response
      */
+    #[ExcludeRouteFromDocs]
     public function update(Request $request, Lecturer $lecturer)
     {
         //
@@ -69,8 +78,8 @@ class VenueController extends Controller
 
     /**
      * Remove the specified resource from storage.
-     * @return \Illuminate\Http\Response
      */
+    #[ExcludeRouteFromDocs]
     public function destroy(Lecturer $lecturer)
     {
         //