#2 payment api documentation

src/Controller/Api/V1/PaymentController.php

@@ -5,6 +5,7 @@
 namespace App\Controller\Api\V1;
 
 use App\Dto\PaymentGatewayDto;
+use App\Dto\PaymentStatusDto;
 use App\Entity\Order;
 use App\Entity\OrderStatus;
 use App\Event\AfterPaymentCallbackHandlerEvent;
@@ -13,6 +14,8 @@
 use App\Order\Workflow\OrderWorkflowFactory;
 use App\Payment\Common\GatewayInterface;
 use App\Payment\PaymentGatewayRegistry;
+use Nelmio\ApiDocBundle\Annotation\Model;
+use OpenApi\Attributes as OA;
 use Symfony\Bridge\Doctrine\Attribute\MapEntity;
 use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 use Symfony\Component\HttpFoundation\JsonResponse;
@@ -30,6 +33,12 @@ public function __construct(
     ) {
     }
 
+    #[OA\Get(description: 'Get the available payment gateways.')]
+    #[OA\Response(
+        response: 200,
+        description: 'A list of available payment gateways.',
+        content: new Model(type: PaymentGatewayDto::class),
+    )]
     #[Route('/gateways', name: 'gateways', methods: 'GET', format: 'json')]
     public function getAvailableGateways(): JsonResponse
     {
@@ -44,6 +53,13 @@ public function getAvailableGateways(): JsonResponse
         return $this->json($gatewayCollection);
     }
 
+    #[OA\Post(
+        description: 'Payment callback handler invoked by the payment gateway.',
+    )]
+    #[OA\Response(
+        response: 200,
+        description: 'Successful handled.',
+    )]
     #[Route('/{order_uuid}/handler', name: 'callback_handler', methods: 'POST', format: 'json')]
     public function paymentCallbackHandler(
         #[MapEntity(mapping: ['order_uuid' => 'uuid'])] Order $order,
@@ -76,6 +92,16 @@ public function paymentCallbackHandler(
         return new Response();
     }
 
+    #[OA\Get(description: 'Get a payment status of the provided order from the payment gateway.')]
+    #[OA\Response(
+        response: 200,
+        description: 'Order payment status.',
+        content: new Model(type: PaymentStatusDto::class),
+    )]
+    #[OA\Response(
+        response: 404,
+        description: 'Order not found.',
+    )]
     #[Route('/{order_uuid}/status', name: 'status', methods: 'GET', format: 'json')]
     public function getPaymentStatus(
         #[MapEntity(mapping: ['order_uuid' => 'uuid'])] Order $order,
@@ -89,13 +115,6 @@ public function getPaymentStatus(
         $event = $this->eventDispatcher->dispatch(new PaymentStatusEvent($order, $statusResponse));
         $statusResponse = $event->paymentStatusResponse;
 
-        return $this->json([
-            'payment_gateway' => $paymentGateway->getId(),
-            'success' => $statusResponse->isSuccessful(),
-            'transaction_id' => $statusResponse->getTransactionId(),
-            'message' => $statusResponse->getMessage(),
-            'code' => $statusResponse->getCode(),
-            'data' => $statusResponse,
-        ]);
+        return $this->json(PaymentStatusDto::makeFromResponse($paymentGateway->getId(), $statusResponse));
     }
 }

src/Dto/PaymentGatewayDto.php

@@ -6,12 +6,21 @@
 
 use App\Payment\Common\GatewayInterface;
 use Symfony\Component\Serializer\Attribute\SerializedName;
+use OpenApi\Attributes as OA;
 
+#[OA\Schema(
+    description: 'Payment Gateway object.'
+)]
 final readonly class PaymentGatewayDto
 {
     public function __construct(
+        #[OA\Property(description: 'Payment gateway id.')]
         public string $id,
+
+        #[OA\Property(description: 'Payment gateway name.')]
         public string $name,
+
+        #[OA\Property(description: 'When test mode is positive, no real payments done.')]
         #[SerializedName('test_mode')] public bool $isTestMode,
     ) {
     }

src/Dto/PaymentStatusDto.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Dto;
+
+use App\Payment\Common\Message\ResponseInterface;
+use Symfony\Component\Serializer\Attribute\SerializedName;
+use OpenApi\Attributes as OA;
+
+#[OA\Schema(
+    description: 'Payment status object.',
+)]
+final readonly class PaymentStatusDto
+{
+    public function __construct(
+
+        #[OA\Property(description: 'Payment gateway id.')]
+        #[SerializedName('payment_gateway')] public string $paymentGatewayId,
+
+        #[OA\Property(description: 'Transaction result.')]
+        #[SerializedName('success')] public bool $isSuccess,
+
+        #[OA\Property(description: 'Transaction id from the payment gateway side.')]
+        #[SerializedName('transaction_id')] public string $transactionId,
+
+        #[OA\Property(description: 'An error message.')]
+        public string $message,
+
+        #[OA\Property(description: 'An error code.')]
+        public string $code,
+
+        #[OA\Property(description: 'A payment status transaction as it was received from the payment gateway.')]
+        public array $data,
+    ) {
+    }
+
+    public static function makeFromResponse(
+        string $paymentGatewayId,
+        ResponseInterface $response,
+    ): self {
+        return new self(
+            paymentGatewayId: $paymentGatewayId,
+            isSuccess: $response->isSuccessful(),
+            transactionId: $response->getTransactionId(),
+            message: $response->getMessage(),
+            code: $response->getCode(),
+            data: $response->getRawData(),
+        );
+    }
+}