From de2c1033479256134f123288c9e26e0cd371ccf1 Mon Sep 17 00:00:00 2001
From: Arman <407448+armanist@users.noreply.github.com>
Date: Thu, 14 May 2026 16:55:47 +0400
Subject: [PATCH 1/8] [#522] Align DemoApi OpenAPI templates and add missing
 endpoint coverage

---
 .../OpenApi/OpenApiAccountController.php.tpl  |  81 +++++
 .../OpenApi/OpenApiAuthController.php.tpl     | 309 ++++--------------
 .../OpenApi/OpenApiCommentController.php.tpl  |  69 ++++
 .../OpenApi/OpenApiPostController.php.tpl     | 257 +++------------
 4 files changed, 275 insertions(+), 441 deletions(-)
 create mode 100644 src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl
 create mode 100644 src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiCommentController.php.tpl

diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl
new file mode 100644
index 00000000..e66a5e10
--- /dev/null
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl
@@ -0,0 +1,81 @@
+<?php
+
+/**
+ * Quantum PHP Framework
+ *
+ * An open source software development framework for PHP
+ *
+ * @package Quantum
+ * @author Arman Ag. <arman.ag@softberg.org>
+ * @copyright Copyright (c) 2018 Softberg LLC (https://softberg.org)
+ * @link http://quantum.softberg.org/
+ * @since 3.0.0
+ */
+
+namespace {{MODULE_NAMESPACE}}\Controllers\OpenApi;
+
+use Quantum\Http\Request;
+
+/**
+ * Class OpenApiAccountController
+ * @package Modules\Api
+ */
+abstract class OpenApiAccountController extends OpenApiController
+{
+    /**
+     * Update user info action
+     * @OA\Put(
+     *    path="/api/account-settings/update",
+     *    tags={"Account"},
+     *    summary="Update user info",
+     *    operationId="updateAccount",
+     *    security={{"bearer_token": {}}},
+     *    @OA\RequestBody(
+     *      required=true,
+     *      @OA\MediaType(
+     *        mediaType="application/json",
+     *        @OA\Schema(
+     *          required={"firstname", "lastname"},
+     *          @OA\Property(property="firstname", type="string"),
+     *          @OA\Property(property="lastname", type="string"),
+     *          example={"firstname": "Jon", "lastname": "Smit"}
+     *        )
+     *      )
+     *    ),
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=401, description="Unauthorized Request"),
+     *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=500, description="Internal Server Error")
+     *  )
+     */
+    abstract public function update(Request $request);
+
+    /**
+     * Update password action
+     * @OA\Put(
+     *    path="/api/account-settings/update-password",
+     *    tags={"Account"},
+     *    summary="Update password",
+     *    operationId="updatePassword",
+     *    security={{"bearer_token": {}}},
+     *    @OA\RequestBody(
+     *      required=true,
+     *      @OA\MediaType(
+     *        mediaType="application/json",
+     *        @OA\Schema(
+     *          required={"current_password", "new_password", "repeat_password"},
+     *          @OA\Property(property="current_password", type="string"),
+     *          @OA\Property(property="new_password", type="string"),
+     *          @OA\Property(property="repeat_password", type="string"),
+     *          example={"current_password": "oldPassword", "new_password": "newPassword", "repeat_password": "newPassword"}
+     *        )
+     *      )
+     *    ),
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=401, description="Unauthorized Request"),
+     *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=500, description="Internal Server Error")
+     *  )
+     */
+    abstract public function updatePassword(Request $request);
+}
diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
index e7295440..ec67e97e 100644
--- a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
@@ -14,7 +14,6 @@
 
 namespace {{MODULE_NAMESPACE}}\Controllers\OpenApi;
 
-use Quantum\Http\Response;
 use Quantum\Http\Request;
 
 /**
@@ -23,7 +22,6 @@ use Quantum\Http\Request;
  */
 abstract class OpenApiAuthController extends OpenApiController
 {
-
     /**
      * Sign in action
      * @OA\Post(
@@ -32,36 +30,20 @@ abstract class OpenApiAuthController extends OpenApiController
      *    summary="Sign in action",
      *    operationId="userSignIn",
      *    @OA\RequestBody(
+     *      required=true,
      *      @OA\MediaType(
-     *      mediaType="application/json",
+     *        mediaType="application/json",
      *        @OA\Schema(
-     *          @OA\Property(
-     *            property="email",
-     *            type="string"
-     *          ),
-     *          @OA\Property(
-     *            property="password",
-     *            type="string"
-     *          ),
-     *          example={"email": "rgaylord@gmail.com", "password": "password"}
+     *          required={"email", "password"},
+     *          @OA\Property(property="email", type="string"),
+     *          @OA\Property(property="password", type="string"),
+     *          example={"email": "mail@example.com", "password": "password"}
      *        )
      *      )
      *    ),
-     *    @OA\Response(
-     *      response=200,
-     *      description="Success",
-     *      @OA\MediaType(
-     *        mediaType="application/json",
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=422,
-     *      description="Unprocessable Entity"
-     *    ),
-     *    @OA\Response(
-     *      response=500,
-     *      description="Internal Server Error"
-     *    )
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function signin(Request $request);
@@ -69,28 +51,14 @@ abstract class OpenApiAuthController extends OpenApiController
     /**
      * Gets the logged-in user data
      * @OA\Get(
-     *     path="/api/me",
-     *     tags={"User"},
-     *     summary="Gets the logged-in user data",
-     *     operationId="me",
-     *     security={
-     *       {"bearer_token": {}}
-     *     },
-     *    @OA\Response(
-     *      response=200,
-     *      description="Success",
-     *      @OA\MediaType(
-     *        mediaType="application/json",
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=401,
-     *      description="Unauthorized Request"
-     *    ),
-     *    @OA\Response(
-     *      response=500,
-     *      description="Internal Server Error"
-     *    )
+     *    path="/api/me",
+     *    tags={"User"},
+     *    summary="Gets the logged-in user data",
+     *    operationId="me",
+     *    security={{"bearer_token": {}}},
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=401, description="Unauthorized Request"),
+     *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function me();
@@ -102,34 +70,12 @@ abstract class OpenApiAuthController extends OpenApiController
      *    tags={"Authentication"},
      *    summary="Sign out action",
      *    operationId="signout",
-     *    @OA\Parameter(
-     *      name="refresh_token",
-     *      description="Refresh token",
-     *      required=true,
-     *      in="header",
-     *      @OA\Schema(
-     *        type="string"
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=200,
-     *      description="Success",
-     *      @OA\MediaType(
-     *        mediaType="application/json",
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=422,
-     *      description="Unprocessable Entity"
-     *    ),
-     *    @OA\Response(
-     *      response=401,
-     *      description="Unauthorized Request"
-     *    ),
-     *    @OA\Response(
-     *      response=500,
-     *      description="Internal Server Error"
-     *    )
+     *    @OA\Parameter(name="refresh_token", description="Refresh token", required=true, in="header", @OA\Schema(type="string")),
+     *    security={{"bearer_token": {}}},
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=401, description="Unauthorized Request"),
+     *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function signout();
@@ -137,49 +83,27 @@ abstract class OpenApiAuthController extends OpenApiController
     /**
      * Sign up action
      * @OA\Post(
-     *  path="/api/signup",
+     *    path="/api/signup",
      *    tags={"Authentication"},
      *    summary="Sign up action",
      *    operationId="signUpApi",
      *    @OA\RequestBody(
+     *      required=true,
      *      @OA\MediaType(
      *        mediaType="application/json",
      *        @OA\Schema(
-     *          @OA\Property(
-     *            property="email",
-     *            type="string",
-     *          ),
-     *          @OA\Property(
-     *            property="password",
-     *            type="string"
-     *          ),
-     *          @OA\Property(
-     *            property="firstname",
-     *            type="string",
-     *          ),
-     *          @OA\Property(
-     *            property="lastname",
-     *            type="string",
-     *          ),
-     *          example={"email": "mail@example.com", "password": "password",  "firstname": "Jon", "lastname": "Smit"}
+     *          required={"email", "password", "firstname", "lastname"},
+     *          @OA\Property(property="email", type="string"),
+     *          @OA\Property(property="password", type="string"),
+     *          @OA\Property(property="firstname", type="string"),
+     *          @OA\Property(property="lastname", type="string"),
+     *          example={"email": "mail@example.com", "password": "password", "firstname": "Jon", "lastname": "Smit"}
      *        )
      *      )
      *    ),
-     *    @OA\Response(
-     *      response=200,
-     *      description="Success",
-     *      @OA\MediaType(
-     *        mediaType="application/json",
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=422,
-     *      description="Unprocessable Entity"
-     *    ),
-     *    @OA\Response(
-     *      response=500,
-     *      description="Internal Server Error"
-     *    )
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function signup(Request $request);
@@ -187,34 +111,14 @@ abstract class OpenApiAuthController extends OpenApiController
     /**
      * Activate action
      * @OA\Get(
-     *  path="/api/activate/{activate_token}",
+     *    path="/api/activate/{token}",
      *    tags={"Authentication"},
      *    summary="Activate action",
      *    operationId="activateProfile",
-     *    @OA\Parameter(
-     *      name="activate_token",
-     *      description="Activate token",
-     *      required=true,
-     *      in="path",
-     *      @OA\Schema(
-     *        type="string"
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=200,
-     *      description="Success",
-     *      @OA\MediaType(
-     *        mediaType="application/json",
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=422,
-     *      description="Unprocessable Entity"
-     *    ),
-     *    @OA\Response(
-     *      response=500,
-     *      description="Internal Server Error"
-     *    )
+     *    @OA\Parameter(name="token", description="Activate token", required=true, in="path", @OA\Schema(type="string")),
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function activate(Request $request);
@@ -222,37 +126,24 @@ abstract class OpenApiAuthController extends OpenApiController
     /**
      * Forget action
      * @OA\Post(
-     *  path="/api/forget",
+     *    path="/api/forget",
      *    tags={"Authentication"},
      *    summary="Forget action",
      *    operationId="forgetPassword",
      *    @OA\RequestBody(
+     *      required=true,
      *      @OA\MediaType(
-     *      mediaType="application/json",
+     *        mediaType="application/json",
      *        @OA\Schema(
-     *          @OA\Property(
-     *            property="username",
-     *            type="string"
-     *          ),
+     *          required={"email"},
+     *          @OA\Property(property="email", type="string"),
      *          example={"email": "mail@example.com"}
      *        )
      *      )
      *    ),
-     *    @OA\Response(
-     *      response=200,
-     *      description="Success",
-     *      @OA\MediaType(
-     *        mediaType="application/json",
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=422,
-     *      description="Unprocessable Entity"
-     *    ),
-     *    @OA\Response(
-     *      response=500,
-     *      description="Internal Server Error"
-     *    )
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function forget(Request $request);
@@ -260,50 +151,25 @@ abstract class OpenApiAuthController extends OpenApiController
     /**
      * Reset action
      * @OA\Post(
-     *  path="/api/reset/{reset_token}",
+     *    path="/api/reset/{token}",
      *    tags={"Authentication"},
      *    summary="Reset action",
      *    operationId="resetPassword",
-     *    @OA\Parameter(
-     *      name="reset_token",
-     *      description="Reset token",
-     *      required=true,
-     *      in="path",
-     *      @OA\Schema(
-     *        type="string"
-     *      )
-     *    ),
+     *    @OA\Parameter(name="token", description="Reset token", required=true, in="path", @OA\Schema(type="string")),
      *    @OA\RequestBody(
+     *      required=true,
      *      @OA\MediaType(
      *        mediaType="application/json",
      *        @OA\Schema(
-     *          @OA\Property(
-     *            property="password",
-     *            type="string"
-     *          ),
-     *          @OA\Property(
-     *            property="repeat_password",
-     *            type="string"
-     *          ),
-     *          example={"password": "password", "repeat_password": "password"}
+     *          required={"password"},
+     *          @OA\Property(property="password", type="string"),
+     *          example={"password": "password"}
      *        )
      *      )
      *    ),
-     *    @OA\Response(
-     *      response=200,
-     *      description="Success",
-     *      @OA\MediaType(
-     *        mediaType="application/json",
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=422,
-     *      description="Unprocessable Entity"
-     *    ),
-     *    @OA\Response(
-     *      response=500,
-     *      description="Internal Server Error"
-     *    )
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function reset(Request $request);
@@ -311,37 +177,26 @@ abstract class OpenApiAuthController extends OpenApiController
     /**
      * Verify action
      * @OA\Post(
-     *  path="/api/verify",
+     *    path="/api/verify",
      *    tags={"Authentication"},
      *    summary="Verify action",
      *    operationId="accountVerify",
      *    @OA\RequestBody(
+     *      required=true,
      *      @OA\MediaType(
-     *      mediaType="application/json",
+     *        mediaType="application/json",
      *        @OA\Schema(
-     *          @OA\Property(
-     *            property="otp_code",
-     *            type="string"
-     *          ),
-     *          example={"otp": "123456", "code": "otp_token"}
+     *          required={"otp", "code"},
+     *          @OA\Property(property="otp", type="integer"),
+     *          @OA\Property(property="code", type="string"),
+     *          example={"otp": 123456, "code": "otp_token"}
      *        )
      *      )
      *    ),
-     *    @OA\Response(
-     *      response=200,
-     *      description="Success",
-     *      @OA\MediaType(
-     *        mediaType="application/json",
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=422,
-     *      description="Unprocessable Entity"
-     *    ),
-     *    @OA\Response(
-     *      response=500,
-     *      description="Internal Server Error"
-     *    )
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=401, description="Unauthorized Request"),
+     *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function verify(Request $request);
@@ -349,34 +204,14 @@ abstract class OpenApiAuthController extends OpenApiController
     /**
      * Resend action
      * @OA\Get(
-     *  path="/api/resend/{otp_token}",
+     *    path="/api/resend/{code}",
      *    tags={"Authentication"},
      *    summary="Resend action",
      *    operationId="resendOTP",
-     *    @OA\Parameter(
-     *      name="otp_token",
-     *      description="OTP token",
-     *      required=true,
-     *      in="path",
-     *      @OA\Schema(
-     *        type="string"
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=200,
-     *      description="Success",
-     *      @OA\MediaType(
-     *        mediaType="application/json",
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=422,
-     *      description="Unprocessable Entity"
-     *    ),
-     *    @OA\Response(
-     *      response=500,
-     *      description="Internal Server Error"
-     *    )
+     *    @OA\Parameter(name="code", description="OTP code", required=true, in="path", @OA\Schema(type="string")),
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function resend();
diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiCommentController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiCommentController.php.tpl
new file mode 100644
index 00000000..5acba11a
--- /dev/null
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiCommentController.php.tpl
@@ -0,0 +1,69 @@
+<?php
+
+/**
+ * Quantum PHP Framework
+ *
+ * An open source software development framework for PHP
+ *
+ * @package Quantum
+ * @author Arman Ag. <arman.ag@softberg.org>
+ * @copyright Copyright (c) 2018 Softberg LLC (https://softberg.org)
+ * @link http://quantum.softberg.org/
+ * @since 3.0.0
+ */
+
+namespace {{MODULE_NAMESPACE}}\Controllers\OpenApi;
+
+use Quantum\Http\Request;
+
+/**
+ * Class OpenApiCommentController
+ * @package Modules\Api
+ */
+abstract class OpenApiCommentController extends OpenApiController
+{
+    /**
+     * Create comment action
+     * @OA\Post(
+     *    path="/api/comments/create/{uuid}",
+     *    tags={"Comments"},
+     *    summary="Create comment action",
+     *    operationId="createComment",
+     *    security={{"bearer_token": {}}},
+     *    @OA\Parameter(name="uuid", description="Post UUID", required=true, in="path", @OA\Schema(type="string")),
+     *    @OA\RequestBody(
+     *      required=true,
+     *      @OA\MediaType(
+     *        mediaType="application/json",
+     *        @OA\Schema(
+     *          required={"content"},
+     *          @OA\Property(property="content", type="string"),
+     *          example={"content": "Great post"}
+     *        )
+     *      )
+     *    ),
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=401, description="Unauthorized Request"),
+     *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=500, description="Internal Server Error")
+     *  )
+     */
+    abstract public function create(Request $request, ?string $lang, string $uuid);
+
+    /**
+     * Delete comment action
+     * @OA\Delete(
+     *    path="/api/comments/delete/{uuid}",
+     *    tags={"Comments"},
+     *    summary="Delete comment action",
+     *    operationId="deleteComment",
+     *    security={{"bearer_token": {}}},
+     *    @OA\Parameter(name="uuid", description="Comment UUID", required=true, in="path", @OA\Schema(type="string")),
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=401, description="Unauthorized Request"),
+     *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=500, description="Internal Server Error")
+     *  )
+     */
+    abstract public function delete(?string $lang, string $uuid);
+}
diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl
index bc9a7cde..7728d1b3 100644
--- a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl
@@ -14,7 +14,6 @@
 
 namespace {{MODULE_NAMESPACE}}\Controllers\OpenApi;
 
-use Quantum\Http\Response;
 use Quantum\Http\Request;
 
 /**
@@ -23,7 +22,6 @@ use Quantum\Http\Request;
  */
 abstract class OpenApiPostController extends OpenApiController
 {
-
     /**
      * Get posts action
      * @OA\Get(
@@ -31,17 +29,11 @@ abstract class OpenApiPostController extends OpenApiController
      *    tags={"Posts"},
      *    summary="Get posts action",
      *    operationId="posts",
-     *    @OA\Response(
-     *      response=200,
-     *      description="Success",
-     *      @OA\MediaType(
-     *        mediaType="application/json",
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=500,
-     *      description="Internal Server Error"
-     *    )
+     *    @OA\Parameter(name="per_page", in="query", required=false, @OA\Schema(type="integer", default=8)),
+     *    @OA\Parameter(name="page", in="query", required=false, @OA\Schema(type="integer", default=1)),
+     *    @OA\Parameter(name="q", in="query", required=false, @OA\Schema(type="string")),
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function posts(Request $request);
@@ -49,34 +41,14 @@ abstract class OpenApiPostController extends OpenApiController
     /**
      * Get post action
      * @OA\Get(
-     *    path="/api/post/{id}",
+     *    path="/api/post/{uuid}",
      *    tags={"Posts"},
      *    summary="Get post action",
      *    operationId="post",
-     *    @OA\Parameter(
-     *      name="id",
-     *      description="Post Id",
-     *      required=true,
-     *      in="path",
-     *      @OA\Schema(
-     *        type="string"
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=200,
-     *      description="Success",
-     *      @OA\MediaType(
-     *        mediaType="application/json",
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=404,
-     *      description="Not Found"
-     *    ),
-     *    @OA\Response(
-     *      response=500,
-     *      description="Internal Server Error"
-     *    )
+     *    @OA\Parameter(name="uuid", description="Post UUID", required=true, in="path", @OA\Schema(type="string")),
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=404, description="Not Found"),
+     *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function post(?string $lang, string $postId);
@@ -88,24 +60,10 @@ abstract class OpenApiPostController extends OpenApiController
      *    tags={"Posts"},
      *    summary="Get my posts action",
      *    operationId="myPosts",
-     *    security={
-     *      {"bearer_token": {}}
-     *    },
-     *    @OA\Response(
-     *      response=200,
-     *      description="Success",
-     *      @OA\MediaType(
-     *        mediaType="application/json",
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=401,
-     *      description="Unauthorized Request"
-     *    ),
-     *    @OA\Response(
-     *      response=500,
-     *      description="Internal Server Error"
-     *    )
+     *    security={{"bearer_token": {}}},
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=401, description="Unauthorized Request"),
+     *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function myPosts();
@@ -113,53 +71,28 @@ abstract class OpenApiPostController extends OpenApiController
     /**
      * Create post action
      * @OA\Post(
-     *  path="/api/my-posts/create",
+     *    path="/api/my-posts/create",
      *    tags={"Posts"},
      *    summary="Create post action",
      *    operationId="create",
-     *    security={
-     *      {"bearer_token": {}
-     *    }},
+     *    security={{"bearer_token": {}}},
      *    @OA\RequestBody(
+     *      required=true,
      *      @OA\MediaType(
      *        mediaType="multipart/form-data",
-     *          @OA\Schema(
-     *            type="object",
-     *            required={"title", "content"},
-     *            @OA\Property(
-     *              property="title",
-     *              type="string",
-     *            ),
-     *            @OA\Property(
-     *              property="content",
-     *              type="string",
-     *            ),
-     *            @OA\Property(
-     *              property="image",
-     *              type="file",
-     *            )
-     *          )
+     *        @OA\Schema(
+     *          type="object",
+     *          required={"title", "content"},
+     *          @OA\Property(property="title", type="string"),
+     *          @OA\Property(property="content", type="string"),
+     *          @OA\Property(property="image", type="string", format="binary")
      *        )
-     *    ),
-     *    @OA\Response(
-     *      response=200,
-     *      description="Success",
-     *      @OA\MediaType(
-     *        mediaType="application/json",
      *      )
      *    ),
-     *    @OA\Response(
-     *      response=401,
-     *      description="Unauthorized Request"
-     *    ),
-     *    @OA\Response(
-     *      response=422,
-     *      description="Unprocessable Entity"
-     *    ),
-     *    @OA\Response(
-     *      response=500,
-     *      description="Internal Server Error"
-     *    )
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=401, description="Unauthorized Request"),
+     *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function create(Request $request);
@@ -167,62 +100,29 @@ abstract class OpenApiPostController extends OpenApiController
     /**
      * Amend post action
      * @OA\Put(
-     *  path="/api/my-posts/amend/{id}",
+     *    path="/api/my-posts/amend/{uuid}",
      *    tags={"Posts"},
      *    summary="Amend post action",
      *    operationId="amend",
-     *    security={
-     *      {"bearer_token": {}
-     *    }},
-     *    @OA\Parameter(
-     *      name="id",
-     *      description="Post id",
-     *      required=true,
-     *      in="path",
-     *      @OA\Schema(
-     *        type="string"
-     *      )
-     *    ),
+     *    security={{"bearer_token": {}}},
+     *    @OA\Parameter(name="uuid", description="Post UUID", required=true, in="path", @OA\Schema(type="string")),
      *    @OA\RequestBody(
+     *      required=true,
      *      @OA\MediaType(
      *        mediaType="multipart/form-data",
      *        @OA\Schema(
      *          type="object",
      *          required={"title", "content"},
-     *            @OA\Property(
-     *              property="title",
-     *              type="string",
-     *            ),
-     *            @OA\Property(
-     *              property="content",
-     *              type="string",
-     *            ),
-     *            @OA\Property(
-     *              property="image",
-     *              type="file",
-     *            )
-     *         )
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=200,
-     *      description="Success",
-     *      @OA\MediaType(
-     *         mediaType="application/json",
+     *          @OA\Property(property="title", type="string"),
+     *          @OA\Property(property="content", type="string"),
+     *          @OA\Property(property="image", type="string", format="binary")
+     *        )
      *      )
      *    ),
-     *    @OA\Response(
-     *      response=401,
-     *      description="Unauthorized Request"
-     *    ),
-     *    @OA\Response(
-     *      response=422,
-     *      description="Unprocessable Entity"
-     *    ),
-     *    @OA\Response(
-     *      response=500,
-     *      description="Internal Server Error"
-     *    )
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=401, description="Unauthorized Request"),
+     *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function amend(Request $request, ?string $lang, string $postId);
@@ -230,41 +130,16 @@ abstract class OpenApiPostController extends OpenApiController
     /**
      * Delete post action
      * @OA\Delete(
-     *    path="/api/my-posts/delete/{id}",
+     *    path="/api/my-posts/delete/{uuid}",
      *    tags={"Posts"},
      *    summary="Delete post action",
      *    operationId="delete",
-     *    security={
-     *      {"bearer_token": {}}
-     *    },
-     *    @OA\Parameter(
-     *      name="id",
-     *      description="Post id",
-     *      required=true,
-     *      in="path",
-     *      @OA\Schema(
-     *        type="string"
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=200,
-     *      description="Success",
-     *      @OA\MediaType(
-     *        mediaType="application/json",
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=401,
-     *      description="Unauthorized Request"
-     *    ),
-     *    @OA\Response(
-     *      response=422,
-     *      description="Unprocessable Entity"
-     *    ),
-     *    @OA\Response(
-     *      response=500,
-     *      description="Internal Server Error"
-     *    )
+     *    security={{"bearer_token": {}}},
+     *    @OA\Parameter(name="uuid", description="Post UUID", required=true, in="path", @OA\Schema(type="string")),
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=401, description="Unauthorized Request"),
+     *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function delete(?string $lang, string $postId);
@@ -272,43 +147,17 @@ abstract class OpenApiPostController extends OpenApiController
     /**
      * Delete post image action
      * @OA\Delete(
-     *    path="/api/my-posts/delete-image/{id}",
+     *    path="/api/my-posts/delete-image/{uuid}",
      *    tags={"Posts"},
      *    summary="Delete post image action",
      *    operationId="deleteImage",
-     *    security={
-     *      {"bearer_token": {}
-     *    }},
-     *    @OA\Parameter(
-     *      name="id",
-     *      description="Post id",
-     *      required=true,
-     *      in="path",
-     *      @OA\Schema(
-     *        type="string"
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=200,
-     *      description="Success",
-     *      @OA\MediaType(
-     *        mediaType="application/json",
-     *      )
-     *    ),
-     *    @OA\Response(
-     *      response=401,
-     *      description="Unauthorized Request"
-     *    ),
-     *    @OA\Response(
-     *      response=422,
-     *      description="Unprocessable Entity"
-     *    ),
-     *    @OA\Response(
-     *      response=500,
-     *      description="Internal Server Error"
-     *    )
+     *    security={{"bearer_token": {}}},
+     *    @OA\Parameter(name="uuid", description="Post UUID", required=true, in="path", @OA\Schema(type="string")),
+     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(response=401, description="Unauthorized Request"),
+     *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function deleteImage(?string $lang, string $postId);
-
 }

From 94f519eb666167a6eb28d77593277a7809d11a49 Mon Sep 17 00:00:00 2001
From: Arman <407448+armanist@users.noreply.github.com>
Date: Thu, 14 May 2026 16:55:47 +0400
Subject: [PATCH 2/8] [#522] Add deterministic success response examples for
 DemoApi endpoints

---
 .../OpenApi/OpenApiAccountController.php.tpl  |  17 ++-
 .../OpenApi/OpenApiAuthController.php.tpl     |  73 ++++++++--
 .../OpenApi/OpenApiCommentController.php.tpl  |  26 +++-
 .../OpenApi/OpenApiPostController.php.tpl     | 131 +++++++++++++++++-
 4 files changed, 227 insertions(+), 20 deletions(-)

diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl
index e66a5e10..6ed6d6fd 100644
--- a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl
@@ -42,7 +42,13 @@ abstract class OpenApiAccountController extends OpenApiController
      *        )
      *      )
      *    ),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={"status": "success", "message": "Updated successfully"}
+     *      )
+     *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=500, description="Internal Server Error")
@@ -71,7 +77,13 @@ abstract class OpenApiAccountController extends OpenApiController
      *        )
      *      )
      *    ),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={"status": "success", "message": "Updated successfully"}
+     *      )
+     *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=500, description="Internal Server Error")
@@ -79,3 +91,4 @@ abstract class OpenApiAccountController extends OpenApiController
      */
     abstract public function updatePassword(Request $request);
 }
+
diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
index ec67e97e..07c99a3a 100644
--- a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
@@ -41,7 +41,13 @@ abstract class OpenApiAuthController extends OpenApiController
      *        )
      *      )
      *    ),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={"status": "success"}
+     *      )
+     *    ),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
@@ -56,7 +62,13 @@ abstract class OpenApiAuthController extends OpenApiController
      *    summary="Gets the logged-in user data",
      *    operationId="me",
      *    security={{"bearer_token": {}}},
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={"status": "success", "data": {"firstname": "Jon", "lastname": "Smit", "email": "mail@example.com"}}
+     *      )
+     *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
@@ -72,7 +84,13 @@ abstract class OpenApiAuthController extends OpenApiController
      *    operationId="signout",
      *    @OA\Parameter(name="refresh_token", description="Refresh token", required=true, in="header", @OA\Schema(type="string")),
      *    security={{"bearer_token": {}}},
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={"status": "success"}
+     *      )
+     *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=500, description="Internal Server Error")
@@ -101,7 +119,13 @@ abstract class OpenApiAuthController extends OpenApiController
      *        )
      *      )
      *    ),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={"status": "success", "message": "Successfully signed up"}
+     *      )
+     *    ),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
@@ -116,7 +140,13 @@ abstract class OpenApiAuthController extends OpenApiController
      *    summary="Activate action",
      *    operationId="activateProfile",
      *    @OA\Parameter(name="token", description="Activate token", required=true, in="path", @OA\Schema(type="string")),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={"status": "success", "message": "Account activated"}
+     *      )
+     *    ),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
@@ -141,7 +171,13 @@ abstract class OpenApiAuthController extends OpenApiController
      *        )
      *      )
      *    ),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={"status": "success", "message": "Check your email"}
+     *      )
+     *    ),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
@@ -167,7 +203,13 @@ abstract class OpenApiAuthController extends OpenApiController
      *        )
      *      )
      *    ),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={"status": "success"}
+     *      )
+     *    ),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
@@ -193,7 +235,13 @@ abstract class OpenApiAuthController extends OpenApiController
      *        )
      *      )
      *    ),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={"status": "success"}
+     *      )
+     *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=500, description="Internal Server Error")
@@ -209,10 +257,17 @@ abstract class OpenApiAuthController extends OpenApiController
      *    summary="Resend action",
      *    operationId="resendOTP",
      *    @OA\Parameter(name="code", description="OTP code", required=true, in="path", @OA\Schema(type="string")),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={"status": "success", "code": "otp_token"}
+     *      )
+     *    ),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function resend();
 }
+
diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiCommentController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiCommentController.php.tpl
index 5acba11a..41c35480 100644
--- a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiCommentController.php.tpl
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiCommentController.php.tpl
@@ -42,7 +42,22 @@ abstract class OpenApiCommentController extends OpenApiController
      *        )
      *      )
      *    ),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={
+     *          "status": "success",
+     *          "message": "Created successfully",
+     *          "data": {
+     *            "uuid": "40f0e8a0-bcd6-11ee-9c66-9f57d21b5b9f",
+     *            "post_uuid": "4e9b8f47-bcd5-11ee-a0f2-fb642f7f26af",
+     *            "user_uuid": "e31a9f20-bcd5-11ee-8fe4-a77a76ad48c2",
+     *            "content": "Great post"
+     *          }
+     *        }
+     *      )
+     *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=500, description="Internal Server Error")
@@ -59,7 +74,13 @@ abstract class OpenApiCommentController extends OpenApiController
      *    operationId="deleteComment",
      *    security={{"bearer_token": {}}},
      *    @OA\Parameter(name="uuid", description="Comment UUID", required=true, in="path", @OA\Schema(type="string")),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={"status": "success", "message": "Deleted successfully"}
+     *      )
+     *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=500, description="Internal Server Error")
@@ -67,3 +88,4 @@ abstract class OpenApiCommentController extends OpenApiController
      */
     abstract public function delete(?string $lang, string $uuid);
 }
+
diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl
index 7728d1b3..bbdf2b18 100644
--- a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl
@@ -32,7 +32,31 @@ abstract class OpenApiPostController extends OpenApiController
      *    @OA\Parameter(name="per_page", in="query", required=false, @OA\Schema(type="integer", default=8)),
      *    @OA\Parameter(name="page", in="query", required=false, @OA\Schema(type="integer", default=1)),
      *    @OA\Parameter(name="q", in="query", required=false, @OA\Schema(type="string")),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={
+     *          "status": "success",
+     *          "data": {
+     *            {
+     *              "uuid": "4e9b8f47-bcd5-11ee-a0f2-fb642f7f26af",
+     *              "title": "Demo Post",
+     *              "content": "<p>Post content</p>",
+     *              "image": "5d8f.../post-image.jpg",
+     *              "date": "2026/05/14 10:30",
+     *              "author": "Jon Smit"
+     *            }
+     *          },
+     *          "pagination": {
+     *            "total_records": 10,
+     *            "current_page": 1,
+     *            "next_page": 2,
+     *            "prev_page": null
+     *          }
+     *        }
+     *      )
+     *    ),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -46,7 +70,35 @@ abstract class OpenApiPostController extends OpenApiController
      *    summary="Get post action",
      *    operationId="post",
      *    @OA\Parameter(name="uuid", description="Post UUID", required=true, in="path", @OA\Schema(type="string")),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={
+     *          "status": "success",
+     *          "data": {
+     *            "uuid": "4e9b8f47-bcd5-11ee-a0f2-fb642f7f26af",
+     *            "title": "Demo Post",
+     *            "content": "<p>Post content</p>",
+     *            "image": "5d8f.../post-image.jpg",
+     *            "date": "2026/05/14 10:30",
+     *            "author": "Jon Smit",
+     *            "comments": {
+     *              {
+     *                "uuid": "40f0e8a0-bcd6-11ee-9c66-9f57d21b5b9f",
+     *                "author": {
+     *                  "firstname": "Jane",
+     *                  "lastname": "Doe",
+     *                  "image": "e31a.../avatar.png"
+     *                },
+     *                "content": "Great post",
+     *                "date": "2026-05-14 10:35"
+     *              }
+     *            }
+     *          }
+     *        }
+     *      )
+     *    ),
      *    @OA\Response(response=404, description="Not Found"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
@@ -61,7 +113,25 @@ abstract class OpenApiPostController extends OpenApiController
      *    summary="Get my posts action",
      *    operationId="myPosts",
      *    security={{"bearer_token": {}}},
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={
+     *          "status": "success",
+     *          "data": {
+     *            {
+     *              "uuid": "4e9b8f47-bcd5-11ee-a0f2-fb642f7f26af",
+     *              "title": "My Post",
+     *              "content": "<p>Post content</p>",
+     *              "image": "5d8f.../post-image.jpg",
+     *              "date": "2026/05/14 10:30",
+     *              "author": "Jon Smit"
+     *            }
+     *          }
+     *        }
+     *      )
+     *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
@@ -89,7 +159,24 @@ abstract class OpenApiPostController extends OpenApiController
      *        )
      *      )
      *    ),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={
+     *          "status": "success",
+     *          "message": "Created successfully",
+     *          "data": {
+     *            "uuid": "4e9b8f47-bcd5-11ee-a0f2-fb642f7f26af",
+     *            "title": "Created Post",
+     *            "content": "<p>Post content</p>",
+     *            "image": "5d8f.../post-image.jpg",
+     *            "date": "2026/05/14 10:30",
+     *            "author": "Jon Smit"
+     *          }
+     *        }
+     *      )
+     *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=500, description="Internal Server Error")
@@ -119,7 +206,24 @@ abstract class OpenApiPostController extends OpenApiController
      *        )
      *      )
      *    ),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={
+     *          "status": "success",
+     *          "message": "Updated successfully",
+     *          "data": {
+     *            "uuid": "4e9b8f47-bcd5-11ee-a0f2-fb642f7f26af",
+     *            "title": "Updated Post",
+     *            "content": "<p>Updated content</p>",
+     *            "image": "5d8f.../post-image.jpg",
+     *            "date": "2026/05/14 11:00",
+     *            "author": "Jon Smit"
+     *          }
+     *        }
+     *      )
+     *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=500, description="Internal Server Error")
@@ -136,7 +240,13 @@ abstract class OpenApiPostController extends OpenApiController
      *    operationId="delete",
      *    security={{"bearer_token": {}}},
      *    @OA\Parameter(name="uuid", description="Post UUID", required=true, in="path", @OA\Schema(type="string")),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={"status": "success", "message": "Deleted successfully"}
+     *      )
+     *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=500, description="Internal Server Error")
@@ -153,7 +263,13 @@ abstract class OpenApiPostController extends OpenApiController
      *    operationId="deleteImage",
      *    security={{"bearer_token": {}}},
      *    @OA\Parameter(name="uuid", description="Post UUID", required=true, in="path", @OA\Schema(type="string")),
-     *    @OA\Response(response=200, description="Success"),
+     *    @OA\Response(
+     *      response=200,
+     *      description="Success",
+     *      @OA\JsonContent(
+     *        example={"status": "success", "message": "Deleted successfully"}
+     *      )
+     *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=500, description="Internal Server Error")
@@ -161,3 +277,4 @@ abstract class OpenApiPostController extends OpenApiController
      */
     abstract public function deleteImage(?string $lang, string $postId);
 }
+

From bf5bd3ddae6fcca928bb8f56115e3312097c0a0d Mon Sep 17 00:00:00 2001
From: Arman <407448+armanist@users.noreply.github.com>
Date: Thu, 14 May 2026 16:55:47 +0400
Subject: [PATCH 3/8] [#522] Add 429 responses and refine deterministic success
 examples

---
 .../OpenApi/OpenApiAccountController.php.tpl          |  4 ++++
 .../Controllers/OpenApi/OpenApiAuthController.php.tpl | 11 +++++++++++
 .../OpenApi/OpenApiCommentController.php.tpl          |  4 ++++
 .../Controllers/OpenApi/OpenApiPostController.php.tpl |  9 +++++++++
 4 files changed, 28 insertions(+)

diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl
index 6ed6d6fd..169ef7f1 100644
--- a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl
@@ -51,6 +51,7 @@ abstract class OpenApiAccountController extends OpenApiController
      *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -86,9 +87,12 @@ abstract class OpenApiAccountController extends OpenApiController
      *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function updatePassword(Request $request);
 }
 
+
+
diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
index 07c99a3a..bc7f973a 100644
--- a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
@@ -49,6 +49,7 @@ abstract class OpenApiAuthController extends OpenApiController
      *      )
      *    ),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -70,6 +71,7 @@ abstract class OpenApiAuthController extends OpenApiController
      *      )
      *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -93,6 +95,7 @@ abstract class OpenApiAuthController extends OpenApiController
      *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -127,6 +130,7 @@ abstract class OpenApiAuthController extends OpenApiController
      *      )
      *    ),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -148,6 +152,7 @@ abstract class OpenApiAuthController extends OpenApiController
      *      )
      *    ),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -179,6 +184,7 @@ abstract class OpenApiAuthController extends OpenApiController
      *      )
      *    ),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -211,6 +217,7 @@ abstract class OpenApiAuthController extends OpenApiController
      *      )
      *    ),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -244,6 +251,7 @@ abstract class OpenApiAuthController extends OpenApiController
      *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -265,9 +273,12 @@ abstract class OpenApiAuthController extends OpenApiController
      *      )
      *    ),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function resend();
 }
 
+
+
diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiCommentController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiCommentController.php.tpl
index 41c35480..2321a8a9 100644
--- a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiCommentController.php.tpl
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiCommentController.php.tpl
@@ -60,6 +60,7 @@ abstract class OpenApiCommentController extends OpenApiController
      *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -83,9 +84,12 @@ abstract class OpenApiCommentController extends OpenApiController
      *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function delete(?string $lang, string $uuid);
 }
 
+
+
diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl
index bbdf2b18..4001a5e9 100644
--- a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl
@@ -57,6 +57,7 @@ abstract class OpenApiPostController extends OpenApiController
      *        }
      *      )
      *    ),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -100,6 +101,7 @@ abstract class OpenApiPostController extends OpenApiController
      *      )
      *    ),
      *    @OA\Response(response=404, description="Not Found"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -133,6 +135,7 @@ abstract class OpenApiPostController extends OpenApiController
      *      )
      *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -179,6 +182,7 @@ abstract class OpenApiPostController extends OpenApiController
      *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -226,6 +230,7 @@ abstract class OpenApiPostController extends OpenApiController
      *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -249,6 +254,7 @@ abstract class OpenApiPostController extends OpenApiController
      *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
@@ -272,9 +278,12 @@ abstract class OpenApiPostController extends OpenApiController
      *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
+     *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
     abstract public function deleteImage(?string $lang, string $postId);
 }
 
+
+

From b1e8503bc1666e83a714ab593b61a672d96846e5 Mon Sep 17 00:00:00 2001
From: Arman <407448+armanist@users.noreply.github.com>
Date: Thu, 14 May 2026 16:55:48 +0400
Subject: [PATCH 4/8] [#522] Document 401 response for resend endpoint

---
 .../src/Controllers/OpenApi/OpenApiAuthController.php.tpl        | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
index bc7f973a..b008c699 100644
--- a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
@@ -272,6 +272,7 @@ abstract class OpenApiAuthController extends OpenApiController
      *        example={"status": "success", "code": "otp_token"}
      *      )
      *    ),
+     *    @OA\Response(response=401, description="Unauthorized Request"),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
      *    @OA\Response(response=429, description="Too Many Requests"),
      *    @OA\Response(response=500, description="Internal Server Error")

From 434d9d5566ad4fdb4d4480cc1aff967b198bf019 Mon Sep 17 00:00:00 2001
From: Arman <407448+armanist@users.noreply.github.com>
Date: Thu, 14 May 2026 16:55:48 +0400
Subject: [PATCH 5/8] [#522] Document signin/verify success tokens in DemoApi
 OpenAPI auth template

---
 .../OpenApi/OpenApiAuthController.php.tpl     | 29 +++++++++++++++++--
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
index b008c699..4efe22b8 100644
--- a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
@@ -45,7 +45,18 @@ abstract class OpenApiAuthController extends OpenApiController
      *      response=200,
      *      description="Success",
      *      @OA\JsonContent(
-     *        example={"status": "success"}
+     *        oneOf={
+     *          @OA\Schema(
+     *            example={
+     *              "status": "success",
+     *              "tokens": {
+     *                "access_token": "base64-jwt-token",
+     *                "refresh_token": "refresh-token"
+     *              }
+     *            }
+     *          ),
+     *          @OA\Schema(example={"status": "success", "code": "otp_token"})
+     *        }
      *      )
      *    ),
      *    @OA\Response(response=422, description="Unprocessable Entity"),
@@ -90,7 +101,13 @@ abstract class OpenApiAuthController extends OpenApiController
      *      response=200,
      *      description="Success",
      *      @OA\JsonContent(
-     *        example={"status": "success"}
+     *        example={
+     *          "status": "success",
+     *          "tokens": {
+     *            "access_token": "base64-jwt-token",
+     *            "refresh_token": "refresh-token"
+     *          }
+     *        }
      *      )
      *    ),
      *    @OA\Response(response=401, description="Unauthorized Request"),
@@ -213,7 +230,13 @@ abstract class OpenApiAuthController extends OpenApiController
      *      response=200,
      *      description="Success",
      *      @OA\JsonContent(
-     *        example={"status": "success"}
+     *        example={
+     *          "status": "success",
+     *          "tokens": {
+     *            "access_token": "base64-jwt-token",
+     *            "refresh_token": "refresh-token"
+     *          }
+     *        }
      *      )
      *    ),
      *    @OA\Response(response=422, description="Unprocessable Entity"),

From b968a7fc345026fcd84e132c9753fbd4740d42e7 Mon Sep 17 00:00:00 2001
From: Arman <407448+armanist@users.noreply.github.com>
Date: Thu, 14 May 2026 16:57:20 +0400
Subject: [PATCH 6/8] [#522] Fix generated OpenAPI spec route path
 concatenation

---
 src/Console/Commands/OpenApiCommand.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Console/Commands/OpenApiCommand.php b/src/Console/Commands/OpenApiCommand.php
index c5183ac8..5c9cf3e2 100644
--- a/src/Console/Commands/OpenApiCommand.php
+++ b/src/Console/Commands/OpenApiCommand.php
@@ -198,7 +198,7 @@ private function openapiRoutes(string $module): string
 
         $route->get("spec", function (): Quantum\Http\Response {
             $fs = Quantum\Storage\Factories\FileSystemFactory::get();
-            return response()->json($fs->getJson(modules_dir() . "' . DS . $module . DS . 'resources' . DS . 'openapi' . DS . 'spec.json"));
+            return response()->json($fs->getJson(modules_dir() . DS . "' . $module . '" . DS . "resources" . DS . "openapi" . DS . "spec.json"));
         });
     });' . PHP_EOL;
     }

From 956254b396198d33ce77f74f276d1e595f28af1f Mon Sep 17 00:00:00 2001
From: Arman <407448+armanist@users.noreply.github.com>
Date: Thu, 14 May 2026 17:14:37 +0400
Subject: [PATCH 7/8] [#522] Update OpenApiCommand path assertion to DS-based
 generated route

---
 tests/Unit/Console/Commands/OpenApiCommandTest.php | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/tests/Unit/Console/Commands/OpenApiCommandTest.php b/tests/Unit/Console/Commands/OpenApiCommandTest.php
index 641fd269..cfe6db7c 100644
--- a/tests/Unit/Console/Commands/OpenApiCommandTest.php
+++ b/tests/Unit/Console/Commands/OpenApiCommandTest.php
@@ -135,10 +135,8 @@ public function testOpenapiRoutesContainsModuleSpecPath(): void
 
         $this->assertStringContainsString('"openapi"', $routes);
         $this->assertStringContainsString('Blog', $routes);
-        $this->assertTrue(
-            strpos($routes, 'resources/openapi/spec.json') !== false
-            || strpos($routes, 'resources\\openapi\\spec.json') !== false
-        );
+        $this->assertStringContainsString('modules_dir() . DS . "Blog"', $routes);
+        $this->assertStringContainsString('. DS . "resources" . DS . "openapi" . DS . "spec.json"', $routes);
     }
 
     public function testCopyResourcesSkipsExcludedFiles(): void

From 4e753bdd4a7105fbffe9dfef240052e7e5513fb0 Mon Sep 17 00:00:00 2001
From: Arman <407448+armanist@users.noreply.github.com>
Date: Thu, 14 May 2026 17:25:50 +0400
Subject: [PATCH 8/8] [#522] Align DemoApi OpenAPI auth/account/post contracts
 and spec path checks

---
 src/Console/Commands/OpenApiCommand.php                  | 2 +-
 .../Controllers/OpenApi/OpenApiAccountController.php.tpl | 7 +++----
 .../Controllers/OpenApi/OpenApiAuthController.php.tpl    | 6 +++---
 .../Controllers/OpenApi/OpenApiPostController.php.tpl    | 9 ++++-----
 4 files changed, 11 insertions(+), 13 deletions(-)

diff --git a/src/Console/Commands/OpenApiCommand.php b/src/Console/Commands/OpenApiCommand.php
index 5c9cf3e2..4821b730 100644
--- a/src/Console/Commands/OpenApiCommand.php
+++ b/src/Console/Commands/OpenApiCommand.php
@@ -126,7 +126,7 @@ public function exec(): void
             return;
         }
 
-        if (request()->routeGroupExists('openapi', $module) && $this->fs->exists($modulePath . DS . 'resources' . DS . 'openApi' . DS . 'spec.json')) {
+        if (request()->routeGroupExists('openapi', $module) && $this->fs->exists($modulePath . DS . 'resources' . DS . 'openapi' . DS . 'spec.json')) {
             $this->error('The Open API specifications already installed for `' . ucfirst($module) . '` module');
             return;
         }
diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl
index 169ef7f1..2a9ddc20 100644
--- a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAccountController.php.tpl
@@ -70,11 +70,11 @@ abstract class OpenApiAccountController extends OpenApiController
      *      @OA\MediaType(
      *        mediaType="application/json",
      *        @OA\Schema(
-     *          required={"current_password", "new_password", "repeat_password"},
+     *          required={"current_password", "new_password", "confirm_password"},
      *          @OA\Property(property="current_password", type="string"),
      *          @OA\Property(property="new_password", type="string"),
-     *          @OA\Property(property="repeat_password", type="string"),
-     *          example={"current_password": "oldPassword", "new_password": "newPassword", "repeat_password": "newPassword"}
+     *          @OA\Property(property="confirm_password", type="string"),
+     *          example={"current_password": "oldPassword", "new_password": "newPassword", "confirm_password": "newPassword"}
      *        )
      *      )
      *    ),
@@ -95,4 +95,3 @@ abstract class OpenApiAccountController extends OpenApiController
 }
 
 
-
diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
index 4efe22b8..880c1c61 100644
--- a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiAuthController.php.tpl
@@ -220,9 +220,10 @@ abstract class OpenApiAuthController extends OpenApiController
      *      @OA\MediaType(
      *        mediaType="application/json",
      *        @OA\Schema(
-     *          required={"password"},
+     *          required={"password", "repeat_password"},
      *          @OA\Property(property="password", type="string"),
-     *          example={"password": "password"}
+     *          @OA\Property(property="repeat_password", type="string"),
+     *          example={"password": "password", "repeat_password": "password"}
      *        )
      *      )
      *    ),
@@ -305,4 +306,3 @@ abstract class OpenApiAuthController extends OpenApiController
 }
 
 
-
diff --git a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl
index 4001a5e9..38298475 100644
--- a/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl
+++ b/src/Module/Templates/DemoApi/src/Controllers/OpenApi/OpenApiPostController.php.tpl
@@ -105,7 +105,7 @@ abstract class OpenApiPostController extends OpenApiController
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
-    abstract public function post(?string $lang, string $postId);
+    abstract public function post(?string $lang, string $uuid);
 
     /**
      * Get my posts action
@@ -234,7 +234,7 @@ abstract class OpenApiPostController extends OpenApiController
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
-    abstract public function amend(Request $request, ?string $lang, string $postId);
+    abstract public function amend(Request $request, ?string $lang, string $uuid);
 
     /**
      * Delete post action
@@ -258,7 +258,7 @@ abstract class OpenApiPostController extends OpenApiController
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
-    abstract public function delete(?string $lang, string $postId);
+    abstract public function delete(?string $lang, string $uuid);
 
     /**
      * Delete post image action
@@ -282,8 +282,7 @@ abstract class OpenApiPostController extends OpenApiController
      *    @OA\Response(response=500, description="Internal Server Error")
      *  )
      */
-    abstract public function deleteImage(?string $lang, string $postId);
+    abstract public function deleteImage(?string $lang, string $uuid);
 }
 
 
-