Build an API explorer for the Events and Orgs endpoints

.gitignore

@@ -32,3 +32,6 @@ laravel.log
 public/build/
 
 *.pem
+
+# Scribe cache and temporary storage
+.scribe

CONTRIBUTING.md

@@ -325,6 +325,7 @@ docker exec "hackgreenville" /bin/bash -c "php artisan import:events"
 [Laravel's Artisan](https://laravel.com/docs/master/artisan) command line tool is heavily leveraged to execute framework and custom commands for development and administration tasks.
 
 - Run `php artisan` to see a full list of availabe commands.
+- The API explorer can be viewed at http://localhost/docs/api and can be recompiled with `php artisan scribe:generate`
 - Running tests `php artisan test`
 - Refreshing events from the remote API: `php artisan import:events`
 - Run database migrations: `php artisan migrate --seed`

EVENTS_API.md

@@ -1,5 +1,8 @@
 # Interacting with the HackGreenville Events API
 
+## Interactive API Explorer
+You can view the interactive API explorer via https://hackgreenville.com/docs/api
+
 ## URLs and Query String Parameters
 By default, results are returned in JSON format.
 

ORGS_API.md

@@ -2,6 +2,9 @@
 
 The _Organizations API_ can be used to build your own custom applications from the structured JSON data representing the [HackGreenville Organizations](https://hackgreenville.com/orgs).
 
+## Interactive API Explorer
+You can view the interactive API explorer via https://hackgreenville.com/docs/api
+
 ## URLs and Query String Parameters
 
 * [Show all organizations](https://hackgreenville.com/api/v0/orgs)

app-modules/api/src/Http/Controllers/EventApiV0Controller.php

@@ -9,6 +9,14 @@
 
 class EventApiV0Controller
 {
+    /**
+     * Events API v0
+     * 
+     * This API provides access to event data stored in the HackGreenville database.
+     * 
+     * @apiResource HackGreenville\Api\Resources\Events\V0\EventCollection
+     * @apiResourceModel App\Models\Event
+     */
     public function __invoke(EventApiV0Request $request)
     {
         return new EventCollection(

app-modules/api/src/Http/Controllers/OrgsApiV0Controller.php

@@ -10,6 +10,14 @@
 
 class OrgsApiV0Controller extends Controller
 {
+    /**
+     * Organizations API v0
+     * 
+     * This API provides access to organization data stored in the HackGreenville database.
+     * 
+     * @apiResource HackGreenville\Api\Resources\Orgs\V0\OrganizationsCollection
+     * @apiResourceModel App\Models\Org
+     */
     public function __invoke(OrgsApiV0Request $request)
     {
         return new OrganizationsCollection(

app-modules/api/src/Http/Requests/EventApiV0Request.php

@@ -27,6 +27,29 @@ public function rules()
                 'date_format:Y-m-d',
                 'after_or_equal:start_date',
             ],
+            'tags' => [
+                'nullable',
+                'sometimes',
+                'integer',
+            ],
+        ];
+    }
+
+    public function queryParameters()
+    {
+        return [
+            'start_date' => [
+                'description' => 'The start date for events filtering (inclusive).',
+                'example' => '2025-01-01',
+            ],
+            'end_date' => [
+                'description' => 'The end date for events filtering (inclusive).',
+                'example' => '2100-12-31',
+            ],
+            'tags' => [
+                'example' => 1,
+                'description' => 'Filter events by organization tag ID.',
+            ],
         ];
     }
 }

app-modules/api/src/Http/Requests/OrgsApiV0Request.php

@@ -21,4 +21,14 @@ public function rules()
             ],
         ];
     }
+
+    public function queryParameters()
+    {
+        return [
+            'tags' => [
+                'example' => 1,
+                'description' => 'Filter organizations by organization tag ID.',
+            ],
+        ];
+    }
 }

composer.json

@@ -40,7 +40,8 @@
         "mockery/mockery": "^1.6",
         "nunomaduro/collision": "^7.7",
         "phpunit/phpunit": "^10.2",
-        "spatie/laravel-ignition": "^2.0"
+        "spatie/laravel-ignition": "^2.0",
+        "knuckleswtf/scribe": "^5.2"
     },
     "autoload": {
         "classmap": [