✨ **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/CityController.php

@@ -5,66 +5,61 @@ namespace App\Http\Controllers\Api;
 use App\Http\Controllers\Controller;
 use App\Models\City;
 use App\Models\Lecturer;
+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 CityController extends Controller
 {
     /**
-     * Display a listing of the resource.
-     * @return \Illuminate\Http\Response
+     * Städte auflisten und durchsuchen
+     *
+     * Öffentlicher Endpunkt; liefert id, name und das zugehörige Land, alphabetisch sortiert. Ohne 'selected' wird die Liste auf 10 Einträge begrenzt.
      */
+    #[QueryParameter(name: 'search', description: 'Teilstring-Suche im Namen der Stadt.', required: false, type: 'string')]
+    #[QueryParameter(name: 'selected', description: 'Lädt gezielt die angegebenen IDs.', required: false, type: 'array')]
     public function index(Request $request)
     {
         return City::query()
-                   ->with(['country:id,name'])
-                   ->select('id', 'name','country_id')
-                   ->orderBy('name')
-                   ->when(
+            ->with(['country:id,name'])
+            ->select('id', 'name', 'country_id')
+            ->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',
-                           $request->input('selected', [])),
-                       fn(Builder $query) => $query->limit(10)
-                   )
-                   ->get();
+            ->when(
+                $request->exists('selected'),
+                fn (Builder $query) => $query->whereIn('id',
+                    $request->input('selected', [])),
+                fn (Builder $query) => $query->limit(10)
+            )
+            ->get();
     }
 
-    /**
-     * Store a newly created resource in storage.
-     * @return \Illuminate\Http\Response
-     */
+    #[ExcludeRouteFromDocs]
     public function store(Request $request)
     {
         //
     }
 
-    /**
-     * Display the specified resource.
-     * @return \Illuminate\Http\Response
-     */
+    #[ExcludeRouteFromDocs]
     public function show(Lecturer $lecturer)
     {
         //
     }
 
-    /**
-     * Update the specified resource in storage.
-     * @return \Illuminate\Http\Response
-     */
+    #[ExcludeRouteFromDocs]
     public function update(Request $request, Lecturer $lecturer)
     {
         //
     }
 
-    /**
-     * Remove the specified resource from storage.
-     * @return \Illuminate\Http\Response
-     */
+    #[ExcludeRouteFromDocs]
     public function destroy(Lecturer $lecturer)
     {
         //