Add controllers and models for order management API

Author: yceruto

tests/Fixtures/App/Controller/CreateOrderController.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenSolid\Api\Tests\Fixtures\App\Controller;
+
+use OpenSolid\Api\Routing\Attribute\Post;
+use OpenSolid\Api\Tests\Fixtures\App\Model\CreateOrderPayload;
+use OpenSolid\Api\Tests\Fixtures\App\Model\OrderView;
+use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;
+
+#[Post(
+    path: '/orders',
+    name: 'api_create_order',
+    description: 'Create an Order',
+    summary: 'Creates a new order resource.',
+    tags: ['Order'],
+)]
+final readonly class CreateOrderController
+{
+    public function __invoke(#[MapRequestPayload] CreateOrderPayload $payload): OrderView
+    {
+        throw new \LogicException('Not implemented.');
+    }
+}

tests/Fixtures/App/Controller/FindOrdersByProductController.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenSolid\Api\Tests\Fixtures\App\Controller;
+
+use OpenSolid\Api\Controller\Model\Paginator\Paginator;
+use OpenSolid\Api\Routing\Attribute\GetCollection;
+use OpenSolid\Api\Tests\Fixtures\App\Model\FindOrdersByProductQuery;
+use OpenSolid\Api\Tests\Fixtures\App\Model\OrderView;
+use Symfony\Component\HttpKernel\Attribute\MapQueryString;
+
+#[GetCollection(
+    path: '/orders/by-product',
+    name: 'api_find_orders_by_product',
+    description: 'Find Orders by Product',
+    summary: 'Retrieves orders filtered by product.',
+    tags: ['Order'],
+)]
+final readonly class FindOrdersByProductController
+{
+    /**
+     * @return Paginator<OrderView>
+     */
+    public function __invoke(#[MapQueryString] ?FindOrdersByProductQuery $query = null): Paginator
+    {
+        throw new \LogicException('Not implemented.');
+    }
+}

tests/Fixtures/App/Controller/FindOrdersController.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenSolid\Api\Tests\Fixtures\App\Controller;
+
+use OpenSolid\Api\Controller\Model\Paginator\Paginator;
+use OpenSolid\Api\Routing\Attribute\GetCollection;
+use OpenSolid\Api\Tests\Fixtures\App\Model\FindOrdersQuery;
+use OpenSolid\Api\Tests\Fixtures\App\Model\OrderView;
+use Symfony\Component\HttpKernel\Attribute\MapQueryString;
+
+#[GetCollection(
+    path: '/orders',
+    name: 'api_find_orders',
+    description: 'Find Orders',
+    summary: 'Retrieves a paginated collection of order resources.',
+    tags: ['Order'],
+)]
+final readonly class FindOrdersController
+{
+    /**
+     * @return Paginator<OrderView>
+     */
+    public function __invoke(#[MapQueryString] ?FindOrdersQuery $query = null): Paginator
+    {
+        throw new \LogicException('Not implemented.');
+    }
+}

tests/Fixtures/App/Model/CreateOrderPayload.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenSolid\Api\Tests\Fixtures\App\Model;
+
+use OpenApi\Attributes as OA;
+use Symfony\Component\Validator\Constraints as Assert;
+
+#[OA\Schema]
+final class CreateOrderPayload
+{
+    #[Assert\NotBlank]
+    #[OA\Property(description: 'The external system ID')]
+    public string $externalId;
+
+    #[Assert\Positive]
+    #[OA\Property(description: 'The total amount in cents', example: 5000)]
+    public int $total;
+
+    #[Assert\Choice(choices: ['USD', 'EUR', 'GBP'])]
+    #[OA\Property(description: 'The currency code', example: 'USD')]
+    public string $currency = 'USD';
+}

tests/Fixtures/App/Model/FindOrdersByProductQuery.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenSolid\Api\Tests\Fixtures\App\Model;
+
+use OpenApi\Attributes as OA;
+use OpenSolid\Api\Controller\Model\Paginator\PaginationParams;
+
+final class FindOrdersByProductQuery
+{
+    use PaginationParams;
+
+    #[OA\QueryParameter(description: 'Filter by external system ID')]
+    public ?string $externalId = null;
+
+    #[OA\QueryParameter(description: 'Filter by product ID', schema: new OA\Schema(format: 'uuid'))]
+    public ?string $productId = null;
+}

tests/Fixtures/App/Model/FindOrdersQuery.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenSolid\Api\Tests\Fixtures\App\Model;
+
+use OpenApi\Attributes as OA;
+use OpenSolid\Api\Controller\Model\Paginator\PaginationParams;
+
+final class FindOrdersQuery
+{
+    use PaginationParams;
+
+    #[OA\QueryParameter(description: 'Filter by external system ID')]
+    public ?string $externalId = null;
+
+    #[OA\QueryParameter(description: 'Filter by order status')]
+    public ?string $status = null;
+
+    #[OA\QueryParameter(description: 'Filter by currency code')]
+    public ?string $currency = null;
+}

tests/Fixtures/App/Model/OrderView.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenSolid\Api\Tests\Fixtures\App\Model;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Schema]
+final readonly class OrderView
+{
+    public function __construct(
+        #[OA\Property(description: 'The order ID', format: 'uuid', example: '019d0121-5df2-77df-be75-8933613d53ab')]
+        public string $id,
+
+        #[OA\Property(description: 'The external system ID')]
+        public string $externalId,
+
+        #[OA\Property(description: 'The order status', example: 'pending')]
+        public string $status,
+
+        #[OA\Property(description: 'The total amount in cents', example: 5000)]
+        public int $total,
+
+        #[OA\Property(description: 'The currency code', example: 'USD')]
+        public string $currency,
+    ) {
+    }
+}

tests/Fixtures/App/OpenApiSpec.php

@@ -13,6 +13,7 @@
 )]
 #[OA\License(name: 'MIT', url: 'https://opensource.org/licenses/MIT')]
 #[OA\Server(url: 'https://127.0.0.1:8000', description: 'Production server (uses live data)')]
+#[OA\Tag(name: 'Order', description: 'The order resource')]
 #[OA\Tag(name: 'Product', description: 'The product resource')]
 class OpenApiSpec
 {

tests/OpenApi/OpenApiValidationTest.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenSolid\Api\Tests\OpenApi;
+
+use OpenSolid\Api\OpenApi\OpenApiGenerator;
+use PHPUnit\Framework\Attributes\Test;
+use Psr\Log\AbstractLogger;
+use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
+
+class OpenApiValidationTest extends KernelTestCase
+{
+    protected function tearDown(): void
+    {
+        parent::tearDown();
+        restore_exception_handler();
+    }
+
+    #[Test]
+    public function generationProducesNoWarningsOrErrors(): void
+    {
+        $generator = self::getContainer()->get(OpenApiGenerator::class);
+        $openApi = $generator->generate();
+
+        $logs = [];
+        $logger = new class($logs) extends AbstractLogger {
+            public function __construct(private array &$logs)
+            {
+            }
+
+            public function log($level, \Stringable|string $message, array $context = []): void
+            {
+                $this->logs[] = ['level' => (string) $level, 'message' => (string) $message];
+            }
+        };
+
+        $openApi->_context->logger = $logger;
+        $openApi->validate();
+
+        $issues = array_filter($logs, static fn (array $log): bool => in_array($log['level'], ['warning', 'error'], true));
+
+        self::assertSame([], $issues, 'OpenAPI validation should produce no warnings or errors');
+    }
+}