Improve API documentation (#284)

Author: romalytvynenko

.github/workflows/build-api-docs.yml

@@ -30,7 +30,10 @@ jobs:
         run: |
           composer config repositories.scramble-pro '{"type": "composer", "url": "https://satis.dedoc.co"}'
           composer config http-basic.satis.dedoc.co ${{ secrets.SCRAMBLE_USERNAME }} ${{ secrets.SCRAMBLE_KEY }}
-          composer require dedoc/scramble-pro:^0.7.4 --dev
+          composer require dedoc/scramble-pro:^0.7.9 --dev
+
+      - name: Build the environment
+        run: composer build
 
       - name: Checkout documentation repository
         uses: actions/checkout@v4

composer.json

@@ -41,7 +41,7 @@
         "twig/twig": "^3.0"
     },
     "require-dev": {
-        "dedoc/scramble": "^0.12.11",
+        "dedoc/scramble": "^0.12.21",
         "larastan/larastan": "^3.4",
         "laravel/pail": "^1.1",
         "laravel/pint": "^1.21",

src/Http/Controllers/Api/ComponentController.php

@@ -13,9 +13,7 @@
 use Cachet\Models\Component;
 use Dedoc\Scramble\Attributes\Group;
 use Dedoc\Scramble\Attributes\QueryParameter;
-use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
 use Illuminate\Http\Response;
-use Illuminate\Pagination\Paginator;
 use Illuminate\Routing\Controller;
 use Spatie\QueryBuilder\AllowedFilter;
 use Spatie\QueryBuilder\QueryBuilder;
@@ -35,8 +33,6 @@ class ComponentController extends Controller
 
     /**
      * List Components
-     *
-     * @response AnonymousResourceCollection<Paginator<ComponentResource>>
      */
     #[QueryParameter('filter[status]', 'Filter by status', type: ComponentStatusEnum::class, example: 1)]
     #[QueryParameter('filter[name]', 'Filter by name.', example: 'My Component')]

src/Http/Controllers/Api/ComponentGroupController.php

@@ -8,14 +8,11 @@
 use Cachet\Concerns\GuardsApiAbilities;
 use Cachet\Data\Requests\ComponentGroup\CreateComponentGroupRequestData;
 use Cachet\Data\Requests\ComponentGroup\UpdateComponentGroupRequestData;
-use Cachet\Http\Resources\Component;
 use Cachet\Http\Resources\ComponentGroup as ComponentGroupResource;
 use Cachet\Models\ComponentGroup;
 use Dedoc\Scramble\Attributes\Group;
 use Dedoc\Scramble\Attributes\QueryParameter;
-use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
 use Illuminate\Http\Response;
-use Illuminate\Pagination\Paginator;
 use Illuminate\Routing\Controller;
 use Spatie\QueryBuilder\QueryBuilder;
 
@@ -26,8 +23,6 @@ class ComponentGroupController extends Controller
 
     /**
      * List Component Groups
-     *
-     * @response AnonymousResourceCollection<Paginator<ComponentGroupResource>>
      */
     #[QueryParameter('per_page', 'How many items to show per page.', type: 'int', default: 15, example: 20)]
     #[QueryParameter('page', 'Which page to show.', type: 'int', example: 2)]

src/Http/Controllers/Api/IncidentController.php

@@ -13,9 +13,7 @@
 use Dedoc\Scramble\Attributes\Group;
 use Dedoc\Scramble\Attributes\QueryParameter;
 use Illuminate\Database\Eloquent\Builder;
-use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
 use Illuminate\Http\Response;
-use Illuminate\Pagination\Paginator;
 use Illuminate\Routing\Controller;
 use Spatie\QueryBuilder\AllowedFilter;
 use Spatie\QueryBuilder\QueryBuilder;
@@ -36,8 +34,6 @@ class IncidentController extends Controller
 
     /**
      * List Incidents
-     *
-     * @return AnonymousResourceCollection<Paginator<IncidentResource>>
      */
     #[QueryParameter('per_page', 'How many items to show per page.', type: 'int', default: 15, example: 20)]
     #[QueryParameter('page', 'Which page to show.', type: 'int', example: 2)]

src/Http/Controllers/Api/IncidentTemplateController.php

@@ -12,9 +12,7 @@
 use Cachet\Models\IncidentTemplate;
 use Dedoc\Scramble\Attributes\Group;
 use Dedoc\Scramble\Attributes\QueryParameter;
-use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
 use Illuminate\Http\Response;
-use Illuminate\Pagination\Paginator;
 use Illuminate\Routing\Controller;
 use Spatie\QueryBuilder\QueryBuilder;
 
@@ -25,8 +23,6 @@ class IncidentTemplateController extends Controller
 
     /**
      * List Incident Templates
-     *
-     * @response AnonymousResourceCollection<Paginator<IncidentTemplateResource>>
      */
     #[QueryParameter('filter[name]', 'Filter by name', example: 'My Template')]
     #[QueryParameter('filter[slug]', 'Filter by slug', example: 'my-template')]

src/Http/Controllers/Api/IncidentUpdateController.php

@@ -13,9 +13,7 @@
 use Cachet\Models\Update;
 use Dedoc\Scramble\Attributes\Group;
 use Dedoc\Scramble\Attributes\QueryParameter;
-use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
 use Illuminate\Http\Response;
-use Illuminate\Pagination\Paginator;
 use Illuminate\Routing\Controller;
 use Spatie\QueryBuilder\AllowedFilter;
 use Spatie\QueryBuilder\AllowedInclude;
@@ -28,8 +26,6 @@ class IncidentUpdateController extends Controller
 
     /**
      * List Incident Updates
-     *
-     * @response AnonymousResourceCollection<Paginator<UpdateResource>>
      */
     #[QueryParameter('per_page', 'How many items to show per page.', type: 'int', default: 15, example: 20)]
     #[QueryParameter('page', 'Which page to show.', type: 'int', example: 2)]

src/Http/Controllers/Api/MetricController.php

@@ -14,9 +14,7 @@
 use Dedoc\Scramble\Attributes\Group;
 use Dedoc\Scramble\Attributes\QueryParameter;
 use Illuminate\Database\Eloquent\Builder;
-use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
 use Illuminate\Http\Response;
-use Illuminate\Pagination\Paginator;
 use Illuminate\Routing\Controller;
 use Spatie\QueryBuilder\QueryBuilder;
 
@@ -27,8 +25,6 @@ class MetricController extends Controller
 
     /**
      * List Metrics
-     *
-     * @response AnonymousResourceCollection<Paginator<MetricResource>>
      */
     #[QueryParameter('filter[name]', 'Filter by name.', example: 'metric name')]
     #[QueryParameter('filter[calc_type]', 'Filter by calculation type.', type: MetricTypeEnum::class)]

src/Http/Controllers/Api/MetricPointController.php

@@ -11,9 +11,7 @@
 use Cachet\Models\MetricPoint;
 use Dedoc\Scramble\Attributes\Group;
 use Dedoc\Scramble\Attributes\QueryParameter;
-use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
 use Illuminate\Http\Response;
-use Illuminate\Pagination\Paginator;
 use Illuminate\Routing\Controller;
 use Spatie\QueryBuilder\QueryBuilder;
 
@@ -24,8 +22,6 @@ class MetricPointController extends Controller
 
     /**
      * List Metric Points
-     *
-     * @response AnonymousResourceCollection<Paginator<MetricPointResource>>
      */
     #[QueryParameter('per_page', 'How many items to show per page.', type: 'int', default: 15, example: 20)]
     #[QueryParameter('page', 'Which page to show.', type: 'int', example: 2)]

src/Http/Controllers/Api/ScheduleController.php

@@ -14,9 +14,7 @@
 use Cachet\Models\Schedule;
 use Dedoc\Scramble\Attributes\Group;
 use Dedoc\Scramble\Attributes\QueryParameter;
-use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
 use Illuminate\Http\Response;
-use Illuminate\Pagination\Paginator;
 use Illuminate\Routing\Controller;
 use Spatie\QueryBuilder\AllowedFilter;
 use Spatie\QueryBuilder\QueryBuilder;
@@ -28,8 +26,6 @@ class ScheduleController extends Controller
 
     /**
      * List Schedules
-     *
-     * @response AnonymousResourceCollection<Paginator<ScheduleResource>>
      */
     #[QueryParameter('filter[name]', 'Filter the resources by name.', example: 'api')]
     #[QueryParameter('filter[status]', 'Filter the resources by status.', type: ScheduleStatusEnum::class)]