chore: Initial setup for OpenAPI 3.1 documentation

Author: matiasperrone

.env.example

@@ -149,3 +149,8 @@ OTEL_TRACES_SAMPLER_PARENT=false
 # OTEL_INSTRUMENTATION_VIEW=true
 # OTEL_INSTRUMENTATION_LIVEWIRE=true
 # OTEL_INSTRUMENTATION_CONSOLE=true
+
+# OpenAPI CONFIG
+# L5_FORMAT_TO_USE_FOR_DOCS=yaml
+L5_SWAGGER_GENERATE_ALWAYS=true # Dev setting
+L5_SWAGGER_OPEN_API_SPEC_VERSION=3.1.0

.gitignore

@@ -15,7 +15,7 @@ Homestead.yaml
 Homestead.json
 .env
 .env.*
-storage/proxies
+storage/*
 /public/assets/jquery-cookie/
 /public/assets/crypto-js/
 /public/assets/bootstrap-tagsinput/

app/Swagger/GenericSchemas.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace App\Swagger\schemas;
+
+use OpenApi\Attributes as OA;
+
+
+#[OA\Schema(
+    schema: 'PaginateDataSchemaResponse',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'total', type: 'integer', example: 6),
+        new OA\Property(property: 'per_page', type: 'integer', example: 5),
+        new OA\Property(property: 'current_page', type: 'integer', example: 1),
+        new OA\Property(property: 'last_page', type: 'integer', example: 2),
+    ],
+    description: 'Base pagination metadata'
+)]
+class PaginateDataSchemaResponseSchema
+{
+}

app/Swagger/OpenApiInfo.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace App\Swagger;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Info(
+    version: "1.0.0",
+    title: "OpenStackID API",
+    description: "OpenStackID IDP API Documentation - OAuth2, OpenID Connect, and User Management",
+    contact: new OA\Contact(
+        name: "OpenStack Foundation",
+        email: "support@openstack.org"
+    ),
+    license: new OA\License(
+        name: "MIT",
+        url: "https://opensource.org/licenses/MIT"
+    )
+)]
+#[OA\Server(
+    url: "/",
+    description: "IDP API Server"
+)]
+#[OA\SecurityScheme(
+    securityScheme: "bearerAuth",
+    type: "http",
+    scheme: "bearer",
+    bearerFormat: "JWT"
+)]
+#[OA\Tag(name: "Users", description: "User management endpoints")]
+#[OA\Tag(name: "Groups", description: "Group management endpoints")]
+class OpenApiInfo
+{
+}
+

composer.json

@@ -24,6 +24,7 @@
     "ext-pdo": "*",
     "beberlei/doctrineextensions": "1.5.0",
     "behat/transliterator": "1.5.0",
+    "darkaonline/l5-swagger": "^9.0",
     "ezyang/htmlpurifier": "v4.17.0",
     "firebase/php-jwt": "6.11.1",
     "get-stream/stream-chat": "^3.10.0",
@@ -59,7 +60,8 @@
     "socialiteproviders/okta": "^4.5.0",
     "socialiteproviders/zoho": "^4.1",
     "sokil/php-isocodes": "^3.0",
-    "vladimir-yuldashev/laravel-queue-rabbitmq": "v14.2.0"
+    "vladimir-yuldashev/laravel-queue-rabbitmq": "v14.2.0",
+    "zircote/swagger-php": "^5.8"
   },
   "require-dev": {
     "fakerphp/faker": "^1.23",