feat: better path sorting for openapi UIs (#6583)

* feat: better path sorting for openapi UIs

* fix: cs fixer

* fix: move the paths sorting logic to the normalizer

* fix: cs fixer

* fix: refactoring for readability

* fix: missing the tags for patch

Author: mrossard

src/OpenApi/Model/Paths.php

@@ -20,8 +20,6 @@ final class Paths
     public function addPath(string $path, PathItem $pathItem): void
     {
         $this->paths[$path] = $pathItem;
-
-        ksort($this->paths);
     }
 
     public function getPath(string $path): ?PathItem

src/OpenApi/Serializer/OpenApiNormalizer.php

@@ -39,7 +39,7 @@ public function __construct(private readonly NormalizerInterface $decorated)
      */
     public function normalize(mixed $object, ?string $format = null, array $context = []): array
     {
-        $pathsCallback = static fn ($decoratedObject): array => $decoratedObject instanceof Paths ? $decoratedObject->getPaths() : [];
+        $pathsCallback = $this->getPathsCallBack();
         $context[AbstractObjectNormalizer::PRESERVE_EMPTY_OBJECTS] = true;
         $context[AbstractObjectNormalizer::SKIP_NULL_VALUES] = true;
         $context[AbstractNormalizer::CALLBACKS] = [
@@ -95,4 +95,46 @@ public function hasCacheableSupportsMethod(): bool
 
         return true;
     }
+
+    private function getPathsCallBack(): \Closure
+    {
+        return static function ($decoratedObject): array {
+            if ($decoratedObject instanceof Paths) {
+                $paths = $decoratedObject->getPaths();
+
+                // sort paths by tags, then by path for each tag
+                uksort($paths, function ($keyA, $keyB) use ($paths) {
+                    $a = $paths[$keyA];
+                    $b = $paths[$keyB];
+
+                    $tagsA = [
+                        ...($a->getGet()?->getTags() ?? []),
+                        ...($a->getPost()?->getTags() ?? []),
+                        ...($a->getPatch()?->getTags() ?? []),
+                        ...($a->getPut()?->getTags() ?? []),
+                        ...($a->getDelete()?->getTags() ?? []),
+                    ];
+                    sort($tagsA);
+
+                    $tagsB = [
+                        ...($b->getGet()?->getTags() ?? []),
+                        ...($b->getPost()?->getTags() ?? []),
+                        ...($b->getPatch()?->getTags() ?? []),
+                        ...($b->getPut()?->getTags() ?? []),
+                        ...($b->getDelete()?->getTags() ?? []),
+                    ];
+                    sort($tagsB);
+
+                    return match (true) {
+                        current($tagsA) === current($tagsB) => $keyA <=> $keyB,
+                        default => current($tagsA) <=> current($tagsB),
+                    };
+                });
+
+                return $paths;
+            }
+
+            return [];
+        };
+    }
 }