[Documentation] Document API endpoints using OpenAPI standard (alexjustesen#1985)

Co-authored-by: alexjustesen <[email protected]>

Author: alexjustesen

app/Http/Controllers/Api/V1/ApiController.php

@@ -4,7 +4,9 @@
 
 use Illuminate\Http\Exceptions\HttpResponseException;
 use Illuminate\Support\Facades\Log;
+use OpenApi\Attributes as OA;
 
+#[OA\Info(title: 'Speedtest Tracker API', version: '1.0.0')]
 abstract class ApiController
 {
     /**

app/Http/Controllers/Api/V1/LatestResult.php

@@ -6,19 +6,25 @@
 use App\Models\Result;
 use Http\Discovery\Exception\NotFoundException;
 use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+use OpenApi\Attributes as OA;
 
 class LatestResult extends ApiController
 {
-    /**
-     * Handle the incoming request.
-     */
+    #[OA\Get(
+        path: '/api/v1/results/latest',
+        description: 'Get the latest result.',
+        responses: [
+            new OA\Response(response: 200, description: 'OK'),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: 'No result found'),
+        ])]
     public function __invoke(Request $request)
     {
         $result = Result::query()
             ->latest()
             ->firstOr(function () {
                 self::throw(
-                    e: new NotFoundException('No results found.'),
+                    e: new NotFoundException('No result found.'),
                     code: 404,
                 );
             });

app/Http/Controllers/Api/V1/ListResults.php

@@ -2,20 +2,25 @@
 
 namespace App\Http\Controllers\Api\V1;
 
-use App\Http\Controllers\Controller;
 use App\Http\Resources\V1\ResultResource;
 use App\Models\Result;
 use Illuminate\Http\Request;
+use Illuminate\Http\Response;
 use Illuminate\Support\Facades\Validator;
+use OpenApi\Attributes as OA;
 use Spatie\QueryBuilder\AllowedFilter;
 use Spatie\QueryBuilder\Enums\FilterOperator;
 use Spatie\QueryBuilder\QueryBuilder;
 
-class ListResults extends Controller
+class ListResults extends ApiController
 {
-    /**
-     * Handle the incoming request.
-     */
+    #[OA\Get(
+        path: '/api/v1/results',
+        description: 'List results.',
+        responses: [
+            new OA\Response(response: Response::HTTP_OK, description: 'OK'),
+            new OA\Response(response: Response::HTTP_UNPROCESSABLE_ENTITY, description: 'Unprocessable Entity'),
+        ])]
     public function __invoke(Request $request)
     {
         $validator = Validator::make($request->all(), [

app/Http/Controllers/Api/V1/ShowResult.php

@@ -6,12 +6,18 @@
 use App\Models\Result;
 use Http\Discovery\Exception\NotFoundException;
 use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+use OpenApi\Attributes as OA;
 
 class ShowResult extends ApiController
 {
-    /**
-     * Handle the incoming request.
-     */
+    #[OA\Get(
+        path: '/api/v1/results/{id}',
+        description: 'Get result.',
+        responses: [
+            new OA\Response(response: 200, description: 'OK'),
+            new OA\Response(response: Response::HTTP_NOT_FOUND, description: 'Result not found'),
+        ])]
     public function __invoke(Request $request, int $id)
     {
         $result = Result::findOr($id, function () {

composer.json

@@ -32,11 +32,12 @@
         "lorisleiva/laravel-actions": "^2.8.5",
         "maennchen/zipstream-php": "^2.4",
         "ryangjchandler/blade-tabler-icons": "^2.3",
-        "spatie/laravel-json-api-paginate": "^1.16",
+        "spatie/laravel-json-api-paginate": "^1.16.1",
         "spatie/laravel-query-builder": "^6.3",
         "spatie/laravel-settings": "^3.4",
         "spatie/laravel-webhook-server": "^3.8.2",
-        "timokoerber/laravel-one-time-operations": "^1.4.4"
+        "timokoerber/laravel-one-time-operations": "^1.4.4",
+        "zircote/swagger-php": "^5.0"
     },
     "require-dev": {
         "fakerphp/faker": "^1.24.1",