API specification generation (#178)

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

@@ -0,0 +1,46 @@
+on:
+  schedule:
+    - cron: '0 7 * * *'
+
+env:
+  DOCS_REPOSITORY: cachethq/docs
+  DOCS_BRANCH: main
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - 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:0.7.0-alpha.1 --dev
+
+      - name: Checkout documentation repository
+        uses: actions/checkout@v4
+        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: Commit and push generated specification
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "Generated API specification from ${{ github.repository }}/${{ github.ref}}@${{ github.sha }}"
+          repository: "docs-repository"

composer.json

@@ -39,6 +39,7 @@
         "twig/twig": "^3.0"
     },
     "require-dev": {
+        "dedoc/scramble": "0.12.0-alpha.1",
         "larastan/larastan": "^3.0",
         "laravel/pail": "^1.1",
         "orchestra/testbench": "^9.5.1",

src/CachetCoreServiceProvider.php

@@ -9,6 +9,10 @@
 use Cachet\Models\Schedule;
 use Cachet\Settings\AppSettings;
 use Cachet\View\ViewManager;
+use Dedoc\Scramble\Scramble;
+use Dedoc\Scramble\Support\Generator\OpenApi;
+use Dedoc\Scramble\Support\Generator\SecurityScheme;
+use Cachet\Documentation\AddAuthenticationToOperation;
 use Filament\Support\Colors\Color;
 use Filament\Support\Facades\FilamentColor;
 use Illuminate\Cache\RateLimiting\Limit;
@@ -73,6 +77,8 @@ public function boot(): void
         FilamentColor::register([
             'cachet' => Color::rgb('rgb(4, 193, 71)'),
         ]);
+
+        $this->configureScramble();
     }
 
     /**
@@ -192,4 +198,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, self-hosted status page system.';
+
+            $openApi->secure(
+                SecurityScheme::http('bearer')
+            );
+        });
+
+        Scramble::registerExtension(AddAuthenticationToOperation::class);
+    }
 }

src/Documentation/AddAuthenticationToOperation.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Cachet\Documentation;
+
+use Dedoc\Scramble\Extensions\OperationExtension;
+use Dedoc\Scramble\Support\Generator\Operation;
+use Dedoc\Scramble\Support\RouteInfo;
+use Illuminate\Support\Str;
+
+class AddAuthenticationToOperation extends OperationExtension
+{
+    public function handle(Operation $operation, RouteInfo $routeInfo)
+    {
+        $hasAuthMiddleware = collect($routeInfo->route->gatherMiddleware())->contains(fn ($m) => Str::startsWith($m, 'auth:'));
+
+        if (! $hasAuthMiddleware) {
+            $operation->addSecurity([]);
+        }
+    }
+}

src/Http/Controllers/Api/ComponentController.php

@@ -8,16 +8,20 @@
 use Cachet\Concerns\GuardsApiAbilities;
 use Cachet\Data\Requests\Component\CreateComponentRequestData;
 use Cachet\Data\Requests\Component\UpdateComponentRequestData;
+use Cachet\Enums\ComponentStatusEnum;
 use Cachet\Http\Resources\Component as ComponentResource;
+use Cachet\Http\Resources\Incident as IncidentResource;
 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;
 
-/**
- * @group Components
- */
+#[Group('Components', weight: 1)]
 class ComponentController extends Controller
 {
     use GuardsApiAbilities;
@@ -33,18 +37,13 @@ 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
-     * @queryParam include Include related resources. Enum: group, incidents. Example: group,incidents
-     * @queryParam filters[name] string Filter by name. Example: My Component
-     * @queryParam filters[status] Filter by status. Enum: 1 , 2, 3. Example: 1
-     * @queryParam filters[enabled] Filter by enabled status. Enum: 0, 1. Example: 1
+     * @response AnonymousResourceCollection<Paginator<ComponentResource>>
      */
+    #[QueryParameter('filter[status]', 'Filter by status', type: ComponentStatusEnum::class, example: 1)]
+    #[QueryParameter('filter[name]', 'Filter by name.', example: 'My Component')]
+    #[QueryParameter('filter[enabled]', 'Filter by enabled status.', type: 'bool', example: '1')]
+    #[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)]
     public function index()
     {
         $components = QueryBuilder::for(Component::class)
@@ -62,12 +61,6 @@ public function index()
 
     /**
      * Create Component
-     *
-     * @apiResource \Cachet\Http\Resources\Component
-     *
-     * @apiResourceModel \Cachet\Models\Component
-     *
-     * @authenticated
      */
     public function store(CreateComponentRequestData $data, CreateComponent $createComponentAction)
     {
@@ -82,12 +75,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)
     {
@@ -102,12 +89,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)
     {
@@ -120,10 +101,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

@@ -10,29 +10,26 @@
 use Cachet\Data\Requests\ComponentGroup\UpdateComponentGroupRequestData;
 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;
 
-/**
- * @group Component Groups
- */
+#[Group('Component Groups', weight: 2)]
 class ComponentGroupController extends Controller
 {
     use GuardsApiAbilities;
 
     /**
      * 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
-     * @queryParam include Include related resources. Enum: components. Example: components
+     * @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)]
     public function index()
     {
         $componentGroups = QueryBuilder::for(ComponentGroup::class)
@@ -45,12 +42,6 @@ public function index()
 
     /**
      * Create Component Group
-     *
-     * @apiResource \Cachet\Http\Resources\ComponentGroup
-     *
-     * @apiResourceModel \Cachet\Models\ComponentGroup
-     *
-     * @authenticated
      */
     public function store(CreateComponentGroupRequestData $data, CreateComponentGroup $createComponentGroupAction)
     {
@@ -63,12 +54,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)
     {
@@ -83,12 +68,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)
     {
@@ -101,12 +80,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(),
             ],
         ]);