From 5a1f2db542780e416fabd8805e19b65d83d96dc6 Mon Sep 17 00:00:00 2001
From: Shahed Nasser <shahednasser@gmail.com>
Date: Fri, 28 Mar 2025 19:29:57 +0200
Subject: [PATCH] docs: added a routes summary section in API reference
 (#12035)

* docs: added routes summary

* added sorting
---
 .../Tags/Section/RoutesSummary/index.tsx      | 99 +++++++++++++++++++
 .../components/Tags/Section/index.tsx         |  5 +-
 2 files changed, 103 insertions(+), 1 deletion(-)
 create mode 100644 www/apps/api-reference/components/Tags/Section/RoutesSummary/index.tsx

diff --git a/www/apps/api-reference/components/Tags/Section/RoutesSummary/index.tsx b/www/apps/api-reference/components/Tags/Section/RoutesSummary/index.tsx
new file mode 100644
index 0000000000..dee3b0dfba
--- /dev/null
+++ b/www/apps/api-reference/components/Tags/Section/RoutesSummary/index.tsx
@@ -0,0 +1,99 @@
+import clsx from "clsx"
+import { getSectionId } from "docs-utils"
+import Link from "next/link"
+import React, { useMemo } from "react"
+import { OpenAPI } from "types"
+import { compareOperations } from "../../../../utils/sort-operations-utils"
+
+type RoutesSummaryProps = {
+  tagName: string
+  paths: OpenAPI.PathsObject
+}
+
+export const RoutesSummary = ({ tagName, paths }: RoutesSummaryProps) => {
+  const sortedOperations = useMemo(() => {
+    const sortedOperations: {
+      endpointPath: string
+      method: string
+      operation: OpenAPI.Operation
+    }[] = []
+
+    Object.entries(paths).forEach(([endpointPath, operations]) => {
+      Object.entries(operations).forEach(([method, operation]) => {
+        sortedOperations.push({
+          endpointPath,
+          method,
+          operation: operation as OpenAPI.Operation,
+        })
+      })
+    })
+
+    sortedOperations.sort((a, b) => {
+      return compareOperations({
+        httpMethodA: a.method,
+        httpMethodB: b.method,
+        summaryA: a.operation.summary,
+        summaryB: b.operation.summary,
+      })
+    })
+
+    return sortedOperations
+  }, [paths])
+
+  if (!sortedOperations.length) {
+    return <></>
+  }
+
+  return (
+    <div
+      className={clsx(
+        "hidden lg:flex flex-col",
+        "bg-medusa-contrast-bg-base rounded-lg",
+        "shadow-elevation-code-block dark:shadow-elevation-code-block-dark"
+      )}
+    >
+      <div className="flex py-0.5 px-1 gap-x-0.75">
+        <span className="text-medusa-contrast-fg-secondary text-code-label">
+          API Routes
+        </span>
+      </div>
+      <div className="flex p-[5px] justify-center items-center w-full">
+        <div
+          className={clsx(
+            "bg-medusa-contrast-bg-subtle rounded-md border border-medusa-contrast-border-bot",
+            "p-0.75 text-code-body w-full flex flex-col gap-y-0.25"
+          )}
+        >
+          {sortedOperations.map(
+            ({ endpointPath, method, operation }, operationIndex) => {
+              const operationId = getSectionId([
+                tagName,
+                (operation as OpenAPI.Operation).operationId,
+              ])
+              return (
+                <span className={clsx("flex gap-x-0.25")} key={operationIndex}>
+                  <span
+                    className={clsx(
+                      "w-[15%]",
+                      method === "get" && "text-medusa-tag-green-icon",
+                      method === "post" && "text-medusa-tag-blue-icon",
+                      method === "delete" && "text-medusa-tag-red-icon"
+                    )}
+                  >
+                    {method.toUpperCase()}
+                  </span>
+                  <Link
+                    href={`#${operationId}`}
+                    className="text-medusa-contrast-fg-secondary hover:text-medusa-contrast-fg-primary w-[85%]"
+                  >
+                    {endpointPath}
+                  </Link>
+                </span>
+              )
+            }
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/www/apps/api-reference/components/Tags/Section/index.tsx b/www/apps/api-reference/components/Tags/Section/index.tsx
index 0ea3822aae..fcb2651100 100644
--- a/www/apps/api-reference/components/Tags/Section/index.tsx
+++ b/www/apps/api-reference/components/Tags/Section/index.tsx
@@ -28,6 +28,7 @@ import TagPaths from "../Paths"
 import useSWR from "swr"
 import basePathUrl from "../../../utils/base-path-url"
 import { getSectionId } from "docs-utils"
+import { RoutesSummary } from "./RoutesSummary"
 
 export type TagSectionProps = {
   tag: OpenAPI.TagObject
@@ -169,7 +170,9 @@ const TagSectionComponent = ({ tag }: TagSectionProps) => {
               />
             </div>
           }
-          codeContent={<></>}
+          codeContent={
+            <RoutesSummary tagName={tag.name} paths={pathsData?.paths || {}} />
+          }
         />
       </SectionContainer>
       {schemaData && (