From a245434d740b55455c978b69d8a5332e84bed887 Mon Sep 17 00:00:00 2001
From: Martin Chaine <martin@casimir.me>
Date: Tue, 3 Jun 2025 09:45:26 +0200
Subject: [PATCH] add attributes to define OpenAPI schema more conveniently

---
 src/OpenApi/Attribute/OrderParameter.php      | 23 +++++++
 .../Attribute/PagerFanta/JsonContent.php      | 60 +++++++++++++++++++
 .../Attribute/PagerFanta/PageParameter.php    | 23 +++++++
 .../Attribute/PagerFanta/PerPageParameter.php | 23 +++++++
 4 files changed, 129 insertions(+)
 create mode 100644 src/OpenApi/Attribute/OrderParameter.php
 create mode 100644 src/OpenApi/Attribute/PagerFanta/JsonContent.php
 create mode 100644 src/OpenApi/Attribute/PagerFanta/PageParameter.php
 create mode 100644 src/OpenApi/Attribute/PagerFanta/PerPageParameter.php

diff --git a/src/OpenApi/Attribute/OrderParameter.php b/src/OpenApi/Attribute/OrderParameter.php
new file mode 100644
index 000000000..1b6e67ecf
--- /dev/null
+++ b/src/OpenApi/Attribute/OrderParameter.php
@@ -0,0 +1,23 @@
+<?php
+
+namespace Wallabag\OpenApi\Attribute;
+
+use OpenApi\Attributes as OA;
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class OrderParameter extends OA\Parameter
+{
+    public function __construct(
+        public readonly string $defaultName = 'order',
+        public readonly string $default = 'desc',
+    ) {
+        parent::__construct(
+            name: $defaultName,
+            in: 'query',
+            description: 'Order of results (asc or desc).',
+            required: false,
+            schema: new OA\Schema(type: 'string', enum: ['asc', 'desc'], default: $default)
+        );
+    }
+}
diff --git a/src/OpenApi/Attribute/PagerFanta/JsonContent.php b/src/OpenApi/Attribute/PagerFanta/JsonContent.php
new file mode 100644
index 000000000..eb0850056
--- /dev/null
+++ b/src/OpenApi/Attribute/PagerFanta/JsonContent.php
@@ -0,0 +1,60 @@
+<?php
+
+namespace Wallabag\OpenApi\Attribute\PagerFanta;
+
+use Nelmio\ApiDocBundle\Attribute\Model;
+use OpenApi\Attributes as OA;
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS)]
+class JsonContent extends OA\JsonContent
+{
+    public function __construct(string|array|null $modelClass = null)
+    {
+        parent::__construct(
+            properties: [
+                new OA\Property(
+                    property: '_embedded',
+                    type: 'object',
+                    properties: [
+                        new OA\Property(
+                            property: 'items',
+                            type: 'array',
+                            items: new OA\Items(ref: new Model(type: $modelClass))
+                        )
+                    ]
+                ),
+                new OA\Property(property: 'page', type: 'integer'),
+                new OA\Property(property: 'limit', type: 'integer'),
+                new OA\Property(property: 'pages', type: 'integer'),
+                new OA\Property(property: 'total', type: 'integer'),
+                new OA\Property(
+                    property: '_links',
+                    type: 'object',
+                    properties: [
+                        new OA\Property(
+                            property: 'self',
+                            type: 'object',
+                            properties: [new OA\Property(property: 'href', type: 'string')]
+                        ),
+                        new OA\Property(
+                            property: 'first',
+                            type: 'object',
+                            properties: [new OA\Property(property: 'href', type: 'string')]
+                        ),
+                        new OA\Property(
+                            property: 'last',
+                            type: 'object',
+                            properties: [new OA\Property(property: 'href', type: 'string')]
+                        ),
+                        new OA\Property(
+                            property: 'next',
+                            type: 'object',
+                            properties: [new OA\Property(property: 'href', type: 'string')]
+                        )
+                    ]
+                )
+            ]
+        );
+    }
+}
diff --git a/src/OpenApi/Attribute/PagerFanta/PageParameter.php b/src/OpenApi/Attribute/PagerFanta/PageParameter.php
new file mode 100644
index 000000000..49460cb5f
--- /dev/null
+++ b/src/OpenApi/Attribute/PagerFanta/PageParameter.php
@@ -0,0 +1,23 @@
+<?php
+
+namespace Wallabag\OpenApi\Attribute\PagerFanta;
+
+use OpenApi\Attributes as OA;
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class PageParameter extends OA\Parameter
+{
+    public function __construct(
+        public readonly string $defaultName = 'page',
+        public readonly int $default = 1,
+    ) {
+        parent::__construct(
+            name: $defaultName,
+            in: 'query',
+            description: 'Requested page number.',
+            required: false,
+            schema: new OA\Schema(type: 'integer', default: $default)
+        );
+    }
+}
diff --git a/src/OpenApi/Attribute/PagerFanta/PerPageParameter.php b/src/OpenApi/Attribute/PagerFanta/PerPageParameter.php
new file mode 100644
index 000000000..098410151
--- /dev/null
+++ b/src/OpenApi/Attribute/PagerFanta/PerPageParameter.php
@@ -0,0 +1,23 @@
+<?php
+
+namespace Wallabag\OpenApi\Attribute\PagerFanta;
+
+use OpenApi\Attributes as OA;
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class PerPageParameter extends OA\Parameter
+{
+    public function __construct(
+        public readonly string $defaultName = 'perPage',
+        public readonly int $default = 30,
+    ) {
+        parent::__construct(
+            name: $defaultName,
+            in: 'query',
+            description: 'Number of items per page.',
+            required: false,
+            schema: new OA\Schema(type: 'integer', default: $default)
+        );
+    }
+}