From a306ace096a33cf8bfe4c9998b3a1ad0658eb3e0 Mon Sep 17 00:00:00 2001
From: Marek Rzytki <rzytki7@gmail.com>
Date: Tue, 16 Jun 2026 09:10:18 +0200
Subject: [PATCH 1/2] Add Taxon documentation to OpenAPI specification

---
 .../TaxonDocumentationModifier.php            | 49 +++++++++++++++++++
 .../Resources/config/integrations/swagger.xml |  5 ++
 2 files changed, 54 insertions(+)
 create mode 100644 src/Sylius/Bundle/ApiBundle/OpenApi/Documentation/TaxonDocumentationModifier.php

diff --git a/src/Sylius/Bundle/ApiBundle/OpenApi/Documentation/TaxonDocumentationModifier.php b/src/Sylius/Bundle/ApiBundle/OpenApi/Documentation/TaxonDocumentationModifier.php
new file mode 100644
index 0000000000..5afd4ab3cd
--- /dev/null
+++ b/src/Sylius/Bundle/ApiBundle/OpenApi/Documentation/TaxonDocumentationModifier.php
@@ -0,0 +1,49 @@
+<?php
+
+/*
+ * This file is part of the Sylius package.
+ *
+ * (c) Sylius Sp. z o.o.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace Sylius\Bundle\ApiBundle\OpenApi\Documentation;
+
+use ApiPlatform\OpenApi\OpenApi;
+
+final class TaxonDocumentationModifier implements DocumentationModifierInterface
+{
+    public function __construct(private string $apiRoute)
+    {
+    }
+
+    public function modify(OpenApi $docs): OpenApi
+    {
+        $path = sprintf('%s/shop/taxons', $this->apiRoute);
+
+        $paths = $docs->getPaths();
+        $pathItem = $paths->getPath($path);
+        $operation = $pathItem?->getGet();
+        if (null === $operation) {
+            return $docs;
+        }
+
+        $operation = $operation
+            ->withSummary('Retrieves the collection of enabled Taxon resources for the current channel.')
+            ->withDescription(
+                'Returns the direct enabled children of the Menu Taxon configured for the current channel. ' .
+                "The Menu Taxon is resolved from the active channel configuration. " .
+                "If no Menu Taxon is configured for the channel, the taxon with code 'category' is used as the default root.",
+            )
+        ;
+
+        $pathItem = $pathItem->withGet($operation);
+        $paths->addPath($path, $pathItem);
+
+        return $docs->withPaths($paths);
+    }
+}
diff --git a/src/Sylius/Bundle/ApiBundle/Resources/config/integrations/swagger.xml b/src/Sylius/Bundle/ApiBundle/Resources/config/integrations/swagger.xml
index 83441409a3..6db0d014cc 100644
--- a/src/Sylius/Bundle/ApiBundle/Resources/config/integrations/swagger.xml
+++ b/src/Sylius/Bundle/ApiBundle/Resources/config/integrations/swagger.xml
@@ -106,5 +106,10 @@
         <service id="sylius_api.open_api.documentation_modifier.address_log_entry" class="Sylius\Bundle\ApiBundle\OpenApi\Documentation\AddressLogEntryDocumentationModifier">
             <tag name="sylius.open_api.modifier" />
         </service>
+
+        <service id="sylius_api.open_api.documentation_modifier.taxon" class="Sylius\Bundle\ApiBundle\OpenApi\Documentation\TaxonDocumentationModifier">
+            <argument>%sylius.security.api_route%</argument>
+            <tag name="sylius.open_api.modifier" />
+        </service>
     </services>
 </container>

From 9c909b5f243d668da675fd4886e987f210006bd5 Mon Sep 17 00:00:00 2001
From: Marek Rzytki <rzytki7@gmail.com>
Date: Fri, 19 Jun 2026 15:54:58 +0200
Subject: [PATCH 2/2] Fix docs description

---
 .../OpenApi/Documentation/TaxonDocumentationModifier.php        | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Sylius/Bundle/ApiBundle/OpenApi/Documentation/TaxonDocumentationModifier.php b/src/Sylius/Bundle/ApiBundle/OpenApi/Documentation/TaxonDocumentationModifier.php
index 5afd4ab3cd..89060005f5 100644
--- a/src/Sylius/Bundle/ApiBundle/OpenApi/Documentation/TaxonDocumentationModifier.php
+++ b/src/Sylius/Bundle/ApiBundle/OpenApi/Documentation/TaxonDocumentationModifier.php
@@ -37,7 +37,7 @@ final class TaxonDocumentationModifier implements DocumentationModifierInterface
             ->withDescription(
                 'Returns the direct enabled children of the Menu Taxon configured for the current channel. ' .
                 "The Menu Taxon is resolved from the active channel configuration. " .
-                "If no Menu Taxon is configured for the channel, the taxon with code 'category' is used as the default root.",
+                "If no Menu Taxon is configured for the channel, the default code is used.",
             )
         ;