API specification generation

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

@@ -0,0 +1,52 @@
+on:
+  schedule:
+    - cron: '0 7 * * *'
+
+env:
+  DOCS_REPOSITORY: romalytvynenko/cachet-docs
+  DOCS_BRANCH: feat/api-docs-generation
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 8.3
+          extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick, fileinfo
+
+      - name: Install dependencies
+        run: composer install
+
+      - name: Install Scramble PRO
+        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:dev-feat/timacdonald-json-api-support --dev
+
+      - name: Checkout documentation repository
+        uses: actions/checkout@v2
+        with:
+          repository: ${{ env.DOCS_REPOSITORY }}
+          ref: ${{ env.DOCS_BRANCH }}
+          path: 'docs-repository'
+
+      - name: Build API docs
+        run: php vendor/bin/testbench scramble:export --path=docs-repository/api-reference/openapi.json
+
+      - name: Setup git config
+        run: |
+          git config --global user.name "GitHub Actions"
+          git config --global user.email "<>"
+
+      - name: Commit and push generated template
+        run: |
+          export COMMIT_MESSAGE="Generated API specification from ${{ github.repository }}/${{ github.ref}}@${{ github.sha }}"
+          cd docs-repository
+          git add .
+          git diff-index --quiet HEAD || (git commit -m "$COMMIT_MESSAGE" && git push)

composer.json

@@ -37,6 +37,7 @@
         "twig/twig": "^3.0"
     },
     "require-dev": {
+        "dedoc/scramble": "dev-feat/endpoint-groups-sorting",
         "larastan/larastan": "^3.0",
         "laravel/pail": "^1.1",
         "orchestra/testbench": "^9.5.1",

src/CachetCoreServiceProvider.php

@@ -3,9 +3,13 @@
 namespace Cachet;
 
 use BladeUI\Icons\Factory;
+use Cachet\Documentation\AddAuthenticationToOperation;
 use Cachet\Models\Incident;
 use Cachet\Models\Schedule;
 use Cachet\Settings\AppSettings;
+use Dedoc\Scramble\Scramble;
+use Dedoc\Scramble\Support\Generator\OpenApi;
+use Dedoc\Scramble\Support\Generator\SecurityScheme;
 use Filament\Support\Colors\Color;
 use Filament\Support\Facades\FilamentColor;
 use Illuminate\Cache\RateLimiting\Limit;
@@ -63,6 +67,8 @@ public function boot(): void
         FilamentColor::register([
             'cachet' => Color::rgb('rgb(4, 193, 71)'),
         ]);
+
+        $this->configureScramble();
     }
 
     /**
@@ -182,4 +188,24 @@ private function registerSchedules(): void
             $schedule->command('cachet:beacon')->daily();
         });
     }
+
+    /**
+     * Scramble is installed as dev dependency hence the class existence check.
+     */
+    private function configureScramble(): void
+    {
+        if (! class_exists(Scramble::class)) {
+            return;
+        }
+
+        Scramble::afterOpenApiGenerated(function (OpenApi $openApi) {
+            $openApi->info->description = 'API documentation for Cachet, the open source status page system.';
+
+            $openApi->secure(
+                SecurityScheme::http('bearer')
+            );
+        });
+
+        Scramble::registerExtension(AddAuthenticationToOperation::class);
+    }
 }

src/Documentation/AddAuthenticationToOperation.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Cachet\Documentation;
+
+use Dedoc\Scramble\Extensions\OperationExtension;
+use Dedoc\Scramble\Support\Generator\Operation;
+use Dedoc\Scramble\Support\RouteInfo;
+
+class AddAuthenticationToOperation extends OperationExtension
+{
+    public function handle(Operation $operation, RouteInfo $routeInfo)
+    {
+        // @todo find out if a route is protected by auth by looking at route's middleware to avoid manually annotating methods
+
+        if (in_array('GET', $routeInfo->route->methods())) {
+            $operation->addSecurity([]);
+        }
+    }
+}

src/Http/Controllers/Api/ComponentController.php

@@ -9,13 +9,12 @@
 use Cachet\Data\Requests\Component\UpdateComponentRequestData;
 use Cachet\Http\Resources\Component as ComponentResource;
 use Cachet\Models\Component;
+use Dedoc\Scramble\Attributes\Group;
 use Illuminate\Http\Response;
 use Illuminate\Routing\Controller;
 use Spatie\QueryBuilder\QueryBuilder;
 
-/**
- * @group Components
- */
+#[Group('Components', weight: 1)]
 class ComponentController extends Controller
 {
     /**
@@ -29,10 +28,6 @@ class ComponentController extends Controller
     /**
      * List Components
      *
-     * @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 Field to sort by. Enum: name, status, enabled. Example: name
@@ -54,12 +49,6 @@ public function index()
 
     /**
      * Create Component
-     *
-     * @apiResource \Cachet\Http\Resources\Component
-     *
-     * @apiResourceModel \Cachet\Models\Component
-     *
-     * @authenticated
      */
     public function store(CreateComponentRequestData $data, CreateComponent $createComponentAction)
     {
@@ -73,10 +62,6 @@ public function store(CreateComponentRequestData $data, CreateComponent $createC
     /**
      * Get Component
      *
-     * @apiResource \Cachet\Http\Resources\Component
-     *
-     * @apiResourceModel \Cachet\Models\Component
-     *
      * @queryParam include Include related resources. Enum: group, incidents. Example: group,incidents
      */
     public function show(Component $component)
@@ -92,12 +77,6 @@ public function show(Component $component)
 
     /**
      * Update Component
-     *
-     * @apiResource \Cachet\Http\Resources\Component
-     *
-     * @apiResourceModel \Cachet\Models\Component
-     *
-     * @authenticated
      */
     public function update(UpdateComponentRequestData $data, Component $component, UpdateComponent $updateComponentAction)
     {
@@ -108,10 +87,6 @@ public function update(UpdateComponentRequestData $data, Component $component, U
 
     /**
      * Delete Component
-     *
-     * @response 204
-     *
-     * @authenticated
      */
     public function destroy(Component $component, DeleteComponent $deleteComponentAction)
     {

src/Http/Controllers/Api/ComponentGroupController.php

@@ -9,22 +9,17 @@
 use Cachet\Data\Requests\ComponentGroup\UpdateComponentGroupRequestData;
 use Cachet\Http\Resources\ComponentGroup as ComponentGroupResource;
 use Cachet\Models\ComponentGroup;
+use Dedoc\Scramble\Attributes\Group;
 use Illuminate\Http\Response;
 use Illuminate\Routing\Controller;
 use Spatie\QueryBuilder\QueryBuilder;
 
-/**
- * @group Component Groups
- */
+#[Group('Component Groups', weight: 2)]
 class ComponentGroupController extends Controller
 {
     /**
      * List Component Groups
      *
-     * @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 Field to sort by. Enum: name, id. Example: name
@@ -42,12 +37,6 @@ public function index()
 
     /**
      * Create Component Group
-     *
-     * @apiResource \Cachet\Http\Resources\ComponentGroup
-     *
-     * @apiResourceModel \Cachet\Models\ComponentGroup
-     *
-     * @authenticated
      */
     public function store(CreateComponentGroupRequestData $data, CreateComponentGroup $createComponentGroupAction)
     {
@@ -59,10 +48,6 @@ public function store(CreateComponentGroupRequestData $data, CreateComponentGrou
     /**
      * Get Component Group
      *
-     * @apiResource \Cachet\Http\Resources\ComponentGroup
-     *
-     * @apiResourceModel \Cachet\Models\ComponentGroup
-     *
      * @queryParam include Include related resources. Enum: components. Example: components
      */
     public function show(ComponentGroup $componentGroup)
@@ -78,12 +63,6 @@ public function show(ComponentGroup $componentGroup)
 
     /**
      * Update Component Group
-     *
-     * @apiResource \Cachet\Http\Resources\ComponentGroup
-     *
-     * @apiResourceModel \Cachet\Models\ComponentGroup
-     *
-     * @authenticated
      */
     public function update(UpdateComponentGroupRequestData $data, ComponentGroup $componentGroup, UpdateComponentGroup $updateComponentGroupAction)
     {
@@ -94,12 +73,6 @@ public function update(UpdateComponentGroupRequestData $data, ComponentGroup $co
 
     /**
      * Delete Component Group
-     *
-     * @apiResource \Cachet\Http\Resources\ComponentGroup
-     *
-     * @apiResourceModel \Cachet\Models\ComponentGroup
-     *
-     * @authenticated
      */
     public function destroy(ComponentGroup $componentGroup, DeleteComponentGroup $deleteComponentGroupAction)
     {

src/Http/Controllers/Api/GeneralController.php

@@ -3,20 +3,15 @@
 namespace Cachet\Http\Controllers\Api;
 
 use Cachet\Cachet;
+use Dedoc\Scramble\Attributes\Group;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Routing\Controller;
 
-/**
- * @group Cachet
- */
+#[Group('Cachet', weight: 0)]
 class GeneralController extends Controller
 {
     /**
      * Test the API
-     *
-     * @response {
-     *     "data": "Pong!"
-     * }
      */
     public function ping(): JsonResponse
     {
@@ -25,17 +20,12 @@ public function ping(): JsonResponse
 
     /**
      * Get Version
-     *
-     * @response {
-     *     "data": {
-     *        "version": "3.x-dev"
-     *    }
-     * }
      */
     public function version(): JsonResponse
     {
         return response()->json([
             'data' => [
+                /** @var "'3.x-dev'" */
                 'version' => Cachet::version(),
             ],
         ]);

src/Http/Controllers/Api/IncidentController.php

@@ -9,14 +9,13 @@
 use Cachet\Data\Requests\Incident\UpdateIncidentRequestData;
 use Cachet\Http\Resources\Incident as IncidentResource;
 use Cachet\Models\Incident;
+use Dedoc\Scramble\Attributes\Group;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Http\Response;
 use Illuminate\Routing\Controller;
 use Spatie\QueryBuilder\QueryBuilder;
 
-/**
- * @group Incidents
- */
+#[Group('Incidents', weight: 3)]
 class IncidentController extends Controller
 {
     /**
@@ -31,10 +30,6 @@ class IncidentController extends Controller
     /**
      * List Incidents
      *
-     * @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 Field to sort by. Enum: name, id, status. Example: status
@@ -58,12 +53,6 @@ public function index()
 
     /**
      * Create Incident
-     *
-     * @apiResource \Cachet\Http\Resources\Incident
-     *
-     * @apiResourceModel \Cachet\Models\Incident
-     *
-     * @authenticated
      */
     public function store(CreateIncidentRequestData $data, CreateIncident $createIncidentAction)
     {
@@ -75,10 +64,6 @@ public function store(CreateIncidentRequestData $data, CreateIncident $createInc
     /**
      * Get Incident
      *
-     * @apiResource \Cachet\Http\Resources\Incident
-     *
-     * @apiResourceModel \Cachet\Models\Incident
-     *
      * @queryParam include Include related resources. Enum: components, updates, user. Example: updates
      */
     public function show(Incident $incident)
@@ -94,12 +79,6 @@ public function show(Incident $incident)
 
     /**
      * Update Incident
-     *
-     * @apiResource \Cachet\Http\Resources\Incident
-     *
-     * @apiResourceModel \Cachet\Models\Incident
-     *
-     * @authenticated
      */
     public function update(UpdateIncidentRequestData $data, Incident $incident, UpdateIncident $updateIncidentAction)
     {
@@ -110,10 +89,6 @@ public function update(UpdateIncidentRequestData $data, Incident $incident, Upda
 
     /**
      * Delete Incident
-     *
-     * @response 204
-     *
-     * @authenticated
      */
     public function destroy(Incident $incident, DeleteIncident $deleteIncidentAction)
     {