Improve Scribe annotations

Author: jbrooksuk

src/Http/Controllers/Api/ComponentController.php

@@ -24,6 +24,12 @@ class ComponentController extends Controller
      * @apiResourceCollection \Cachet\Http\Resources\Component
      *
      * @apiResourceModel \Cachet\Models\Component
+     *
+     * @queryParam per_page int How many items to show per page. Example: 20
+     * @queryParam page int Which page to show. Example: 2
+     * @queryParam sort string Field to sort by. Enum: name, status, enabled Example: name
+     * @queryParam include string Include related resources. Enum: group, incidents Example: group,incidents
+     * @queryParam filters string[] Filter the resources. Example: name=api
      */
     public function index()
     {

src/Http/Controllers/Api/ComponentGroupController.php

@@ -24,6 +24,11 @@ class ComponentGroupController extends Controller
      * @apiResource \Cachet\Http\Resources\ComponentGroup
      *
      * @apiResourceModel \Cachet\Models\ComponentGroup
+     *
+     * @queryParam per_page int How many items to show per page. Example: 20
+     * @queryParam page int Which page to show. Example: 2
+     * @queryParam sort string Field to sort by. Enum: name, id Example: name
+     * @queryParam include string Include related resources. Enum: components Example: components
      */
     public function index()
     {

src/Http/Controllers/Api/IncidentController.php

@@ -25,6 +25,11 @@ class IncidentController extends Controller
      * @apiResourceCollection \Cachet\Http\Resources\Incident
      *
      * @apiResourceModel \Cachet\Models\Incident
+     *
+     * @queryParam per_page int How many items to show per page. Example: 20
+     * @queryParam page int Which page to show. Example: 2
+     * @queryParam sort string Field to sort by. Enum: name, id, status Example: status
+     * @queryParam include string Include related resources. Enum: updates Example: updates
      */
     public function index()
     {

src/Http/Controllers/Api/IncidentTemplateController.php

@@ -24,6 +24,11 @@ class IncidentTemplateController extends Controller
      * @apiResourceCollection \Cachet\Http\Resources\IncidentTemplate
      *
      * @apiResourceModel \Cachet\Models\IncidentTemplate
+     *
+     * @queryParam per_page int How many items to show per page. Example: 20
+     * @queryParam page int Which page to show. Example: 2
+     * @queryParam sort string Field to sort by. Enum: name, slug, id Example: name
+     * @queryParam filters string[] Filter the resources.
      */
     public function index()
     {

src/Http/Controllers/Api/IncidentUpdateController.php

@@ -25,6 +25,11 @@ class IncidentUpdateController extends Controller
      * @apiResourceCollection \Cachet\Http\Resources\IncidentUpdate
      *
      * @apiResourceModel \Cachet\Models\IncidentUpdate
+     *
+     * @queryParam per_page int How many items to show per page. Example: 20
+     * @queryParam page int Which page to show. Example: 2
+     * @queryParam sort string Field to sort by. Enum: name, created_at Example: name
+     * @queryParam filters string[] Filter the resources.
      */
     public function index(Incident $incident)
     {

src/Http/Controllers/Api/MetricController.php

@@ -25,6 +25,12 @@ class MetricController extends Controller
      * @apiResourceCollection \Cachet\Http\Resources\Metric
      *
      * @apiResourceModel \Cachet\Models\Metric
+     *
+     * @queryParam per_page int How many items to show per page. Example: 20
+     * @queryParam page int Which page to show. Example: 2
+     * @queryParam sort string Field to sort by. Enum: name, order, id enabled Example: name
+     * @queryParam include string Include related resources. Enum: points Example: points
+     * @queryParam filters string[] Filter the resources. Example: name=api
      */
     public function index()
     {

src/Http/Controllers/Api/MetricPointController.php

@@ -23,6 +23,11 @@ class MetricPointController extends Controller
      * @apiResourceCollection \Cachet\Http\Resources\MetricPoint
      *
      * @apiResourceModel \Cachet\Models\MetricPoint
+     *
+     * @queryParam per_page int How many items to show per page. Example: 20
+     * @queryParam page int Which page to show. Example: 2
+     * @queryParam sort string Field to sort by. Enum: name, order, id Example: name
+     * @queryParam include string Include related resources. Enum: metric Example: metric
      */
     public function index(Metric $metric)
     {

src/Http/Controllers/Api/ScheduleController.php

@@ -24,6 +24,12 @@ class ScheduleController extends Controller
      * @apiResourceCollection \Cachet\Http\Resources\Schedule
      *
      * @apiResourceModel \Cachet\Models\Schedule
+     *
+     * @queryParam per_page int How many items to show per page. Example: 20
+     * @queryParam page int Which page to show. Example: 2
+     * @queryParam sort string Field to sort by. Enum: name, id, scheduled_at, completed_at, enabled Example: name
+     * @queryParam include string Include related resources. Enum: components Example: components
+     * @queryParam filters string[] Filter the resources. Example: name=api
      */
     public function index()
     {

src/Http/Requests/CreateComponentRequest.php

@@ -33,4 +33,22 @@ public function rules(): array
             'component_group_id' => ['int', 'min:0', Rule::exists('component_groups', 'id')],
         ];
     }
+
+    /**
+     * Specify body parameter documentation for Scribe.
+     */
+    public function bodyParameters(): array
+    {
+        return [
+            'status' => [
+                'description' => 'The status of the component. See [Component Statuses](/v3.x/guide/components#component-statuses) for more information.',
+                'example' => '1',
+                'required' => false,
+                'schema' => [
+                    'type' => 'integer',
+                    'enum' => ComponentStatusEnum::cases(),
+                ],
+            ],
+        ];
+    }
 }