Scribe Annotations (#130)

cachethq · Nov 24, 2024 · 6aa5924 · 6aa5924
1 parent d7a6f1b
commit 6aa5924
Show file tree

Hide file tree

Showing 24 changed files with 343 additions and 43 deletions.
diff --git a/composer.json b/composer.json
@@ -53,6 +53,7 @@
     "autoload-dev": {
         "psr-4": {
             "Cachet\\Tests\\": "tests",
+            "Cachet\\Database\\Factories\\": "database/factories",
             "Workbench\\App\\": "workbench/app/",
             "Workbench\\Database\\Factories\\": "workbench/database/factories/",
             "Workbench\\Database\\Seeders\\": "workbench/database/seeders/"

diff --git a/database/factories/ScheduleComponentFactory.php b/database/factories/ScheduleComponentFactory.php
@@ -4,13 +4,12 @@
 
 use Cachet\Enums\ComponentStatusEnum;
 use Cachet\Models\Component;
-use Cachet\Models\Incident;
 use Cachet\Models\Schedule;
 use Cachet\Models\ScheduleComponent;
 use Illuminate\Database\Eloquent\Factories\Factory;
 
 /**
- * @extends Factory<Incident>
+ * @extends Factory<ScheduleComponent>
  */
 class ScheduleComponentFactory extends Factory
 {

diff --git a/src/Http/Controllers/Api/ComponentController.php b/src/Http/Controllers/Api/ComponentController.php
@@ -13,10 +13,16 @@
 use Illuminate\Routing\Controller;
 use Spatie\QueryBuilder\QueryBuilder;
 
+/**
+ * @group Components
+ */
 class ComponentController extends Controller
 {
     /**
-     * List Components.
+     * List Components
+     *
+     * @apiResourceCollection \Cachet\Http\Resources\Component
+     * @apiResourceModel \Cachet\Models\Component
      */
     public function index()
     {
@@ -30,7 +36,11 @@ public function index()
     }
 
     /**
-     * Create Component.
+     * Create Component
+     *
+     * @apiResource \Cachet\Http\Resources\Component
+     * @apiResourceModel \Cachet\Models\Component
+     * @authenticated
      */
     public function store(CreateComponentRequest $request, CreateComponent $createComponentAction)
     {
@@ -40,7 +50,10 @@ public function store(CreateComponentRequest $request, CreateComponent $createCo
     }
 
     /**
-     * Get Component.
+     * Get Component
+     *
+     * @apiResource \Cachet\Http\Resources\Component
+     * @apiResourceModel \Cachet\Models\Component
      */
     public function show(Component $component)
     {
@@ -50,7 +63,11 @@ public function show(Component $component)
     }
 
     /**
-     * Update Component.
+     * Update Component
+     *
+     * @apiResource \Cachet\Http\Resources\Component
+     * @apiResourceModel \Cachet\Models\Component
+     * @authenticated
      */
     public function update(UpdateComponentRequest $request, Component $component, UpdateComponent $updateComponentAction)
     {
@@ -60,7 +77,10 @@ public function update(UpdateComponentRequest $request, Component $component, Up
     }
 
     /**
-     * Delete Component.
+     * Delete Component
+     *
+     * @response 204
+     * @authenticated
      */
     public function destroy(Component $component, DeleteComponent $deleteComponentAction)
     {

diff --git a/src/Http/Controllers/Api/ComponentGroupController.php b/src/Http/Controllers/Api/ComponentGroupController.php
@@ -13,10 +13,16 @@
 use Illuminate\Routing\Controller;
 use Spatie\QueryBuilder\QueryBuilder;
 
+/**
+ * @group Component Groups
+ */
 class ComponentGroupController extends Controller
 {
     /**
-     * List Component Groups.
+     * List Component Groups
+     *
+     * @apiResource \Cachet\Http\Resources\ComponentGroup
+     * @apiResourceModel \Cachet\Models\ComponentGroup
      */
     public function index()
     {
@@ -29,7 +35,11 @@ public function index()
     }
 
     /**
-     * Create Component Group.
+     * Create Component Group
+     *
+     * @apiResource \Cachet\Http\Resources\ComponentGroup
+     * @apiResourceModel \Cachet\Models\ComponentGroup
+     * @authenticated
      */
     public function store(CreateComponentGroupRequest $request, CreateComponentGroup $createComponentGroupAction)
     {
@@ -41,7 +51,10 @@ public function store(CreateComponentGroupRequest $request, CreateComponentGroup
     }
 
     /**
-     * Get Component Group.
+     * Get Component Group
+     *
+     * @apiResource \Cachet\Http\Resources\ComponentGroup
+     * @apiResourceModel \Cachet\Models\ComponentGroup
      */
     public function show(ComponentGroup $componentGroup)
     {
@@ -52,6 +65,10 @@ public function show(ComponentGroup $componentGroup)
 
     /**
      * Update Component Group
+     *
+     * @apiResource \Cachet\Http\Resources\ComponentGroup
+     * @apiResourceModel \Cachet\Models\ComponentGroup
+     * @authenticated
      */
     public function update(UpdateComponentGroupRequest $request, ComponentGroup $componentGroup, UpdateComponentGroup $updateComponentGroupAction)
     {
@@ -63,7 +80,11 @@ public function update(UpdateComponentGroupRequest $request, ComponentGroup $com
     }
 
     /**
-     * Delete Component Group.
+     * Delete Component Group
+     *
+     * @apiResource \Cachet\Http\Resources\ComponentGroup
+     * @apiResourceModel \Cachet\Models\ComponentGroup
+     * @authenticated
      */
     public function destroy(ComponentGroup $componentGroup, DeleteComponentGroup $deleteComponentGroupAction)
     {

diff --git a/src/Http/Controllers/Api/GeneralController.php b/src/Http/Controllers/Api/GeneralController.php
@@ -6,18 +6,31 @@
 use Illuminate\Http\JsonResponse;
 use Illuminate\Routing\Controller;
 
+/**
+ * @group Cachet
+ */
 class GeneralController extends Controller
 {
     /**
-     * Ping the API.
+     * Test the API
+     *
+     * @response {
+     *     "data": "Pong!"
+     * }
      */
     public function ping(): JsonResponse
     {
         return response()->json(['data' => 'Pong!']);
     }
 
     /**
-     * Get the Cachet version.
+     * Get Version
+     *
+     * @response {
+     *     "data": {
+     *        "version": "3.x-dev"
+     *    }
+     * }
      */
     public function version(): JsonResponse
     {

diff --git a/src/Http/Controllers/Api/IncidentController.php b/src/Http/Controllers/Api/IncidentController.php
@@ -14,10 +14,16 @@
 use Illuminate\Routing\Controller;
 use Spatie\QueryBuilder\QueryBuilder;
 
+/**
+ * @group Incidents
+ */
 class IncidentController extends Controller
 {
     /**
-     * List Incidents.
+     * List Incidents
+     *
+     * @apiResourceCollection \Cachet\Http\Resources\Incident
+     * @apiResourceModel \Cachet\Models\Incident
      */
     public function index()
     {
@@ -34,7 +40,11 @@ public function index()
     }
 
     /**
-     * Create Incident.
+     * Create Incident
+     *
+     * @apiResource \Cachet\Http\Resources\Incident
+     * @apiResourceModel \Cachet\Models\Incident
+     * @authenticated
      */
     public function store(CreateIncidentRequest $request, CreateIncident $createIncidentAction)
     {
@@ -44,7 +54,10 @@ public function store(CreateIncidentRequest $request, CreateIncident $createInci
     }
 
     /**
-     * Get Incident.
+     * Get Incident
+     *
+     * @apiResource \Cachet\Http\Resources\Incident
+     * @apiResourceModel \Cachet\Models\Incident
      */
     public function show(Incident $incident)
     {
@@ -54,7 +67,11 @@ public function show(Incident $incident)
     }
 
     /**
-     * Update Incident.
+     * Update Incident
+     *
+     * @apiResource \Cachet\Http\Resources\Incident
+     * @apiResourceModel \Cachet\Models\Incident
+     * @authenticated
      */
     public function update(UpdateIncidentRequest $request, Incident $incident, UpdateIncident $updateIncidentAction)
     {
@@ -64,7 +81,10 @@ public function update(UpdateIncidentRequest $request, Incident $incident, Updat
     }
 
     /**
-     * Delete Incident.
+     * Delete Incident
+     *
+     * @response 204
+     * @authenticated
      */
     public function destroy(Incident $incident, DeleteIncident $deleteIncidentAction)
     {

diff --git a/src/Http/Controllers/Api/IncidentTemplateController.php b/src/Http/Controllers/Api/IncidentTemplateController.php
@@ -13,10 +13,16 @@
 use Illuminate\Routing\Controller;
 use Spatie\QueryBuilder\QueryBuilder;
 
+/**
+ * @group Incident Templates
+ */
 class IncidentTemplateController extends Controller
 {
     /**
-     * List Incident Templates.
+     * List Incident Templates
+     *
+     * @apiResourceCollection \Cachet\Http\Resources\IncidentTemplate
+     * @apiResourceModel \Cachet\Models\IncidentTemplate
      */
     public function index()
     {
@@ -29,7 +35,11 @@ public function index()
     }
 
     /**
-     * Create Incident Template.
+     * Create Incident Template
+     *
+     * @apiResource \Cachet\Http\Resources\IncidentTemplate
+     * @apiResourceModel \Cachet\Models\IncidentTemplate
+     * @authenticated
      */
     public function store(CreateIncidentTemplateRequest $request)
     {
@@ -39,7 +49,10 @@ public function store(CreateIncidentTemplateRequest $request)
     }
 
     /**
-     * Get Incident Template.
+     * Get Incident Template
+     *
+     * @apiResource \Cachet\Http\Resources\IncidentTemplate
+     * @apiResourceModel \Cachet\Models\IncidentTemplate
      */
     public function show(IncidentTemplate $incidentTemplate)
     {
@@ -49,7 +62,11 @@ public function show(IncidentTemplate $incidentTemplate)
     }
 
     /**
-     * Update Incident Template.
+     * Update Incident Template
+     *
+     * @apiResource \Cachet\Http\Resources\IncidentTemplate
+     * @apiResourceModel \Cachet\Models\IncidentTemplate
+     * @authenticated
      */
     public function update(UpdateIncidentTemplateRequest $request, IncidentTemplate $incidentTemplate)
     {
@@ -59,7 +76,10 @@ public function update(UpdateIncidentTemplateRequest $request, IncidentTemplate
     }
 
     /**
-     * Delete Incident Template.
+     * Delete Incident Template
+     *
+     * @response 204
+     * @authenticated
      */
     public function destroy(IncidentTemplate $incidentTemplate)
     {

diff --git a/src/Http/Controllers/Api/IncidentUpdateController.php b/src/Http/Controllers/Api/IncidentUpdateController.php
@@ -14,10 +14,16 @@
 use Illuminate\Routing\Controller;
 use Spatie\QueryBuilder\QueryBuilder;
 
+/**
+ * @group Incident Updates
+ */
 class IncidentUpdateController extends Controller
 {
     /**
-     * List Incident Updates.
+     * List Incident Updates
+     *
+     * @apiResourceCollection \Cachet\Http\Resources\IncidentUpdate
+     * @apiResourceModel \Cachet\Models\IncidentUpdate
      */
     public function index(Incident $incident)
     {
@@ -31,7 +37,11 @@ public function index(Incident $incident)
     }
 
     /**
-     * Create Incident Update.
+     * Create Incident Update
+     *
+     * @apiResource \Cachet\Http\Resources\IncidentUpdate
+     * @apiResourceModel \Cachet\Models\IncidentUpdate
+     * @authenticated
      */
     public function store(CreateIncidentUpdateRequest $request, Incident $incident, CreateIncidentUpdate $createIncidentUpdateAction)
     {
@@ -41,7 +51,10 @@ public function store(CreateIncidentUpdateRequest $request, Incident $incident,
     }
 
     /**
-     * Get Incident Update.
+     * Get Incident Update
+     *
+     * @apiResource \Cachet\Http\Resources\IncidentUpdate
+     * @apiResourceModel \Cachet\Models\IncidentUpdate
      */
     public function show(Incident $incident, IncidentUpdate $incidentUpdate)
     {
@@ -51,7 +64,11 @@ public function show(Incident $incident, IncidentUpdate $incidentUpdate)
     }
 
     /**
-     * Update Incident Update.
+     * Update Incident Update
+     *
+     * @apiResource \Cachet\Http\Resources\IncidentUpdate
+     * @apiResourceModel \Cachet\Models\IncidentUpdate
+     * @authenticated
      */
     public function update(UpdateIncidentUpdateRequest $request, Incident $incident, IncidentUpdate $incidentUpdate, UpdateIncidentUpdate $updateIncidentUpdateAction)
     {
@@ -61,7 +78,10 @@ public function update(UpdateIncidentUpdateRequest $request, Incident $incident,
     }
 
     /**
-     * Delete Incident Update.
+     * Delete Incident Update
+     *
+     * @response 204
+     * @authenticated
      */
     public function destroy(Incident $incident, IncidentUpdate $incidentUpdate, DeleteIncidentUpdate $deleteIncidentUpdateAction)
     {