Chore | Initial setup for OpenAPI 3.1.2 documentation (#103)

* chore: Initial setup for OpenAPI 3.1 documentation

Signed-off-by: matiasperrone-exo <matias.perrone@exomindset.co>

* chore: Move to OpenAPI v3.1.2 so UI supports it

Signed-off-by: matiasperrone-exo <matias.perrone@exomindset.co>

* chore: Add Basic schema which will be referenced by all the other Models schemas

Signed-off-by: matiasperrone-exo <matias.perrone@exomindset.co>

* chore: change name for Base schema

Signed-off-by: matiasperrone-exo <matias.perrone@exomindset.co>

* chore: Add requested changes

Signed-off-by: matiasperrone-exo <matias.perrone@exomindset.co>

* chore: remove unneeded schema

Signed-off-by: matiasperrone-exo <matias.perrone@exomindset.co>

* update .env.example with right values for OpenAPI docs

Signed-off-by: matiasperrone-exo <matias.perrone@exomindset.co>

* chore: change API name in config

Signed-off-by: matiasperrone-exo <matias.perrone@exomindset.co>

---------

Signed-off-by: matiasperrone-exo <matias.perrone@exomindset.co>

Author: matiasperrone-exo

.env.example

@@ -149,3 +149,12 @@ OTEL_TRACES_SAMPLER_PARENT=false
 # OTEL_INSTRUMENTATION_VIEW=true
 # OTEL_INSTRUMENTATION_LIVEWIRE=true
 # OTEL_INSTRUMENTATION_CONSOLE=true
+
+# OpenAPI CONFIG (former Swagger)
+
+L5_SWAGGER_CONST_HOST=${APP_URL}
+L5_SWAGGER_CONST_AUTH_URL='/oauth2/auth'
+L5_SWAGGER_CONST_TOKEN_URL='/oauth2/token'
+# L5_FORMAT_TO_USE_FOR_DOCS=yaml
+L5_SWAGGER_GENERATE_ALWAYS=true # Dev setting
+L5_SWAGGER_OPEN_API_SPEC_VERSION=3.1.2

.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,35 @@
+<?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
+{
+}
+
+#[OA\Schema(
+    schema: 'Base',
+    type: 'object',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer', description: 'Unique identifier', example: 1),
+        new OA\Property(property: 'created_at', type: 'integer', description: 'Creation timestamp (epoch)', example: 1609459200),
+        new OA\Property(property: 'updated_at', type: 'integer', description: 'Last update timestamp (epoch)', example: 1609459200),
+    ],
+    description: 'Base serializer fields'
+)]
+class BaseSchema
+{
+}

app/Swagger/OpenApiInfo.php

@@ -0,0 +1,26 @@
+<?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: "Apache 2.0",
+        url: "http://www.apache.org/licenses/LICENSE-2.0"
+    )
+)]
+#[OA\Server(
+    url: L5_SWAGGER_CONST_HOST,
+    description: "IDP API Server"
+)]
+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",