radiant-docs 0.1.33 → 0.1.37

package/template/src/components/endpoint/PlaygroundForm.astro

@@ -33,10 +33,12 @@ const {
   bodyDefaultKind,
 } = Astro.props;
 const config = await getConfig();
-const proxyEnabled = config.playground?.proxy !== false;
-const proxyUrl =
-  import.meta.env.PUBLIC_PROXY_URL ||
-  "https://docs-proxy.stefanjoseph-dev.workers.dev";
+const configuredProxyUrl =
+  typeof import.meta.env.PUBLIC_PROXY_URL === "string"
+    ? import.meta.env.PUBLIC_PROXY_URL.trim()
+    : "";
+const proxyUrl = configuredProxyUrl || "/_platform/proxy";
+const proxyEnabled = config.playground?.proxy !== false && proxyUrl.length > 0;
 const formattedBodyDescription = bodyDescription
   ? await renderMarkdown(bodyDescription)
   : null;
@@ -538,20 +540,22 @@ const sectionVariantFieldNames = Object.fromEntries(
       <button
         @click="sendRequest($event)"
         :disabled="loading"
-        class="m-px flex items-center gap-1.5 px-4 py-[5px] text-sm font-medium rounded-lg bg-neutral-900 text-white/95 hover:text-white shadow-[inset_0_1px_0_rgb(255,255,255,0.3),0_0_0_1px_var(--color-neutral-800)] duration-200 whitespace-nowrap cursor-pointer relative before:absolute before:inset-0 before:shadow-sm before:rounded-lg before:bg-transparent disabled:opacity-70"
+        class="m-px font-[350] relative flex h-8 items-center gap-2 rounded-lg [corner-shape:superellipse(1.2)] bg-linear-to-b from-neutral-900/85 to-neutral-900 px-3 text-[13px] text-white shadow-sm dark:bg-white dark:text-neutral-900 transition-all duration-200 whitespace-nowrap cursor-pointer disabled:opacity-70 disabled:cursor-not-allowed"
       >
-        <span
-          class="flex items-center gap-2"
-          x-bind:class="loading ? 'opacity-0':''"
-        >
+      <span class="flex items-center gap-2">
+          <Icon
+            x-show="!loading"
+            class="size-3.5 -ml-px"
+            name="lucide:square-arrow-up-right"
+          />
+          <Icon
+            x-show="loading"
+            x-cloak
+            class="size-3.5 animate-spin -ml-px"
+            name="lucide:loader"
+          />
           Send <span class="hidden xs:inline">Request</span>
-          <Icon class="size-4" name="lucide:square-arrow-up-right" />
         </span>
-        <Icon
-          x-show="loading"
-          class="size-4 absolute left-1/2 -translate-x-1/2 top-1/2 -translate-y-1/2 animate-spin **:stroke-3"
-          name="lucide:loader"
-        />
       </button>
     </PlaygroundBar>
 
@@ -578,7 +582,7 @@ const sectionVariantFieldNames = Object.fromEntries(
             }
 
             return (
-              <div class="border border-neutral-200 shadow-xs rounded-xl p-4">
+              <div class="border border-neutral-200 shadow-xs rounded-xl p-4 pb-0 [&_[role='region']]:border-b-0">
                 <Accordion title={headers[key]} defaultOpen titleSize="xl">
                   {key === "body" && formattedBodyDescription && (
                     <div

package/template/src/components/sidebar/SidebarEndpointLink.astro

@@ -1,28 +1,28 @@
 ---
-import { slugify } from "../../lib/utils";
+import Tag from "../ui/Tag.astro";
+import { buildOpenApiEndpointHref } from "../../lib/utils";
 import { methodColors } from "../../lib/utils";
 
 interface Props {
   method: string;
   path: string;
   summary?: string;
+  title?: string;
+  tag?: string;
   parentSlug?: string;
 }
 
-const { method, path: pathStr, summary, parentSlug = "" } = Astro.props;
+const { method, path: pathStr, summary, title, tag, parentSlug = "" } = Astro.props;
 
-// Generate slug from path and method (matching routes.ts logic)
-const pathSlug = pathStr
-  .replace(/^\//, "") // Remove leading slash
-  .replace(/\//g, "-") // Replace slashes with hyphens
-  .replace(/\{[^}]+\}/g, "param"); // Replace path params like {id} with "param"
-
-const methodSlug = slugify(method);
-const endpointSlug = pathSlug ? `${pathSlug}-${methodSlug}` : methodSlug;
-const href = parentSlug ? `/${parentSlug}/${endpointSlug}` : `/${endpointSlug}`;
+const normalizedMethod = method.toLowerCase();
+const href = buildOpenApiEndpointHref({
+  path: pathStr,
+  method: normalizedMethod,
+  groupSlug: parentSlug,
+});
 
 // Use summary for title, fallback to method + path
-const text = summary || pathStr;
+const text = title || summary || `${normalizedMethod.toUpperCase()} ${pathStr}`;
 
 // Normalize paths for comparison (remove trailing slashes)
 const currentPath = Astro.url.pathname.replace(/\/$/, "");
@@ -42,10 +42,13 @@ const isActive = currentPath === targetPath;
   <span
     class:list={[
       "px-1 py-px mr-1.5 border rounded-md text-[10px] font-semibold uppercase",
-      methodColors[method],
+      methodColors[normalizedMethod] ?? methodColors.get,
     ]}
   >
-    {method.toLowerCase() !== "delete" ? method : "del"}
+    {normalizedMethod !== "delete" ? normalizedMethod : "del"}
   </span>
-  {text}
+  <div class="flex items-center gap-2 min-w-0">
+    <span>{text}</span>
+    {tag && <Tag>{tag}</Tag>}
+  </div>
 </a>

package/template/src/components/sidebar/SidebarOpenApiPageLink.astro

@@ -0,0 +1,56 @@
+---
+import type { NavOpenApiPage } from "../../lib/validation";
+import { loadOpenApiSpec } from "../../lib/validation";
+import { parseOpenApiEndpoint } from "../../lib/utils";
+import SidebarEndpointLink from "./SidebarEndpointLink.astro";
+
+interface Props {
+  item: NavOpenApiPage;
+  parentSlug?: string;
+}
+
+const { item, parentSlug = "" } = Astro.props;
+
+const parsedEndpoint = parseOpenApiEndpoint(item.openapi.endpoint);
+if (!parsedEndpoint) {
+  throw new Error(
+    `Invalid OpenAPI endpoint format "${item.openapi.endpoint}". Expected "METHOD /path".`,
+  );
+}
+
+const openApiDoc = await loadOpenApiSpec(item.openapi.source);
+const openApiPaths = openApiDoc?.paths ?? {};
+const endpointMethod = parsedEndpoint.method.toLowerCase();
+
+let matchedPath: string | null = null;
+let endpointSummary: string | undefined;
+
+for (const [pathStr, pathItem] of Object.entries(openApiPaths)) {
+  if (!pathItem || typeof pathItem !== "object") continue;
+  if (pathStr.toLowerCase() !== parsedEndpoint.path) continue;
+
+  const operation = (pathItem as any)[endpointMethod];
+  if (!operation) continue;
+
+  matchedPath = pathStr;
+  if (typeof operation.summary === "string") {
+    endpointSummary = operation.summary;
+  }
+  break;
+}
+
+if (!matchedPath) {
+  throw new Error(
+    `OpenAPI endpoint "${item.openapi.endpoint}" was not found in source "${item.openapi.source}".`,
+  );
+}
+---
+
+<SidebarEndpointLink
+  method={endpointMethod}
+  path={matchedPath}
+  summary={endpointSummary}
+  title={item.title}
+  tag={item.tag}
+  parentSlug={parentSlug}
+/>

package/template/src/components/ui/Icon.astro

@@ -1,5 +1,6 @@
 ---
 import { Icon as AstroIcon } from "astro-icon/components";
+import { resolveStaticAssetUrl } from "../../lib/static-asset-url";
 
 interface Props {
   name: string | undefined | null;
@@ -19,7 +20,7 @@ const isLocal = !isUrl && !isIconify;
 // Files from src/content/docs are copied to public root by copyContentAssets plugin
 let src = name;
 if (isLocal) {
-  src = name.startsWith("/") ? name : `/${name}`;
+  src = resolveStaticAssetUrl(name.startsWith("/") ? name : `/${name}`);
 }
 ---
 

package/template/src/components/user/Image.astro

@@ -2,6 +2,7 @@
 import type { HTMLAttributes } from "astro/types";
 import { validateProps } from "../../lib/component-error";
 import { renderMarkdown } from "../../lib/utils";
+import { resolveStaticAssetUrl } from "../../lib/static-asset-url";
 
 interface Props extends HTMLAttributes<"img"> {
   src: string;
@@ -11,6 +12,9 @@ interface Props extends HTMLAttributes<"img"> {
 const { title, zoom = true, ...attrs } = Astro.props as Props;
 const zoomEnabled = zoom !== false;
 const attrsRecord = attrs as Record<string, unknown>;
+if (typeof attrsRecord.src === "string") {
+  attrsRecord.src = resolveStaticAssetUrl(attrsRecord.src);
+}
 const rawStyle = attrsRecord.style;
 const rawWidth = attrsRecord.width;
 const zoomAttrs: Record<string, unknown> = { ...attrsRecord };

package/template/src/layouts/Layout.astro

@@ -12,6 +12,7 @@ import Header from "../components/Header.astro";
 import Footer from "../components/Footer.astro";
 import AskAiWidget from "../components/chat/AskAiWidget";
 import { ClientRouter } from "astro:transitions";
+import { resolveStaticAssetUrl } from "../lib/static-asset-url";
 
 interface Props {
   pageTitle?: string;
@@ -52,7 +53,7 @@ const canonicalUrl = new URL(
   Astro.site ?? Astro.url,
 ).toString();
 const ogImageUrl = new URL(
-  routePathToOgImagePath(Astro.url.pathname),
+  resolveStaticAssetUrl(routePathToOgImagePath(Astro.url.pathname)),
   Astro.site ?? Astro.url,
 );
 const ogImageHref = ogImageUrl.toString();
@@ -144,7 +145,11 @@ if (isDev && hasAskAiDevConfig) {
     />
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width" />
-    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link
+      rel="icon"
+      type="image/svg+xml"
+      href={resolveStaticAssetUrl("/favicon.svg")}
+    />
     <meta name="generator" content={Astro.generator} />
     <link rel="canonical" href={canonicalUrl} />
     <meta property="og:url" content={canonicalUrl} />
@@ -211,7 +216,7 @@ if (isDev && hasAskAiDevConfig) {
 
     <!-- Main Content -->
     <div
-      class="mx-1 mt-1 px-4 sm:px-6 lg:pl-[calc(288px+32px)] pt-16 lg:pr-8 bg-white"
+      class="mx-1 mt-1 px-4 sm:px-6 lg:pl-[calc(288px+32px)] pt-16 lg:pr-8 bg-background"
       data-vaul-scale-chrome
     >
       <main

package/template/src/lib/pagefind.ts

@@ -1,4 +1,5 @@
 // Pagefind TypeScript types and wrapper
+import { resolveStaticAssetUrl } from "./static-asset-url";
 
 export interface PagefindSearchResult {
   id: string;
@@ -50,7 +51,7 @@ export interface PagefindInstance {
 let pagefindInstance: PagefindInstance | null = null;
 
 function getPagefindScriptUrl(): string {
-  return "/pagefind/pagefind.js";
+  return resolveStaticAssetUrl("/pagefind/pagefind.js");
 }
 
 export async function getPagefind(): Promise<PagefindInstance | null> {

package/template/src/lib/routes.ts

@@ -2,17 +2,20 @@ import {
   getConfig,
   type NavGroup,
   type NavPage,
+  type NavOpenApiPage,
   type NavMenuItem,
   type NavOpenApi,
   loadOpenApiSpec,
 } from "./validation";
-import { deriveTitleFromEntryId, slugify } from "./utils";
-import path from "node:path";
+import {
+  buildOpenApiEndpointSlug,
+  deriveTitleFromEntryId,
+  parseOpenApiEndpoint,
+  slugify,
+} from "./utils";
 import { getCollection } from "astro:content";
 
-// NOTE: You need to define NavPageItem to include strings, pages, and groups
-// Since the input array is already validated, we can use the types from validation.ts
-type NavPageItem = string | NavPage;
+type MdxNavPageItem = string | NavPage;
 
 // Base route interface
 export interface BaseRoute {
@@ -55,7 +58,7 @@ export function resolveMdxPageTitle(args: {
 }
 
 function processPageItem(
-  item: NavPageItem,
+  item: MdxNavPageItem,
   parentSlug: string = "",
   docs: any[],
 ): MdxRoute {
@@ -92,53 +95,106 @@ function processPageItem(
   };
 }
 
-function processGroup(
+type OpenApiOperationLookup = {
+  method: string;
+  path: string;
+  operation: any;
+};
+
+function findOpenApiOperation(args: {
+  openApiDoc: any;
+  endpointMethod: string;
+  endpointPath: string;
+}): OpenApiOperationLookup | null {
+  const paths = args.openApiDoc?.paths ?? {};
+  const targetMethod = args.endpointMethod.toLowerCase();
+  const targetPath = args.endpointPath.toLowerCase();
+
+  for (const [pathStr, pathItem] of Object.entries(paths)) {
+    if (!pathItem || typeof pathItem !== "object") continue;
+    if (pathStr.toLowerCase() !== targetPath) continue;
+
+    const operation = (pathItem as any)[targetMethod];
+    if (!operation) continue;
+
+    return {
+      method: targetMethod,
+      path: pathStr,
+      operation,
+    };
+  }
+
+  return null;
+}
+
+async function processOpenApiPageItem(
+  item: NavOpenApiPage,
+  parentSlug: string = "",
+): Promise<OpenApiRoute> {
+  const parsedEndpoint = parseOpenApiEndpoint(item.openapi.endpoint);
+  if (!parsedEndpoint) {
+    throw new Error(
+      `Invalid OpenAPI endpoint format "${item.openapi.endpoint}". Expected "METHOD /path".`,
+    );
+  }
+
+  const openApiDoc = await loadOpenApiSpec(item.openapi.source);
+  const matchedOperation = findOpenApiOperation({
+    openApiDoc,
+    endpointMethod: parsedEndpoint.method,
+    endpointPath: parsedEndpoint.path,
+  });
+
+  if (!matchedOperation) {
+    throw new Error(
+      `OpenAPI endpoint "${item.openapi.endpoint}" was not found in source "${item.openapi.source}".`,
+    );
+  }
+
+  const endpointSlug = buildOpenApiEndpointSlug(
+    matchedOperation.path,
+    matchedOperation.method,
+  );
+  const fullSlug = parentSlug ? `${parentSlug}/${endpointSlug}` : endpointSlug;
+  const title =
+    normalizeTitle(item.title) ??
+    normalizeTitle(matchedOperation.operation.summary) ??
+    `${matchedOperation.method.toUpperCase()} ${matchedOperation.path}`;
+
+  return {
+    type: "openapi",
+    slug: fullSlug,
+    filePath: item.openapi.source,
+    title,
+    openApiPath: matchedOperation.path,
+    openApiMethod: matchedOperation.method,
+  };
+}
+
+async function processGroup(
   group: NavGroup,
   parentSlug: string = "",
   docs: any[],
-): Route[] {
+): Promise<Route[]> {
   let routes: Route[] = [];
   const groupSlug = slugify(group.group);
   const currentPrefix = parentSlug ? `${parentSlug}/${groupSlug}` : groupSlug;
 
-  group.pages.forEach((item) => {
+  for (const item of group.pages) {
     // Check if it's a simple page or a page object
     if (typeof item === "string" || "page" in item) {
-      routes.push(processPageItem(item as NavPageItem, currentPrefix, docs));
+      routes.push(processPageItem(item, currentPrefix, docs));
     } else if ("group" in item) {
       // Nested group
       routes = routes.concat(
-        processGroup(item as NavGroup, currentPrefix, docs),
+        await processGroup(item as NavGroup, currentPrefix, docs),
       );
+    } else if ("openapi" in item) {
+      routes.push(await processOpenApiPageItem(item, currentPrefix));
     }
-  });
-
-  return routes;
-}
-
-// Helper function to parse endpoint string (same as in validation.ts)
-function parseEndpointString(
-  endpointStr: string,
-): { method: string; path: string } | null {
-  const trimmed = endpointStr.trim();
-  const parts = trimmed.split(/\s+/);
-
-  if (parts.length !== 2) {
-    return null;
   }
 
-  const method = parts[0].toUpperCase();
-  let path = parts[1];
-
-  // Ensure path starts with /
-  if (!path.startsWith("/")) {
-    path = "/" + path;
-  }
-
-  // Normalize path to lowercase for comparison
-  const normalizedPath = path.toLowerCase();
-
-  return { method, path: normalizedPath };
+  return routes;
 }
 
 // Helper function to check if an endpoint matches include/exclude filters
@@ -156,7 +212,7 @@ function shouldIncludeEndpoint(
   // If include is specified, only include matching endpoints
   if (include) {
     return include.some((entry) => {
-      const parsed = parseEndpointString(entry);
+      const parsed = parseOpenApiEndpoint(entry);
       if (!parsed) return false;
       return `${parsed.method} ${parsed.path}` === endpointKey;
     });
@@ -165,7 +221,7 @@ function shouldIncludeEndpoint(
   // If exclude is specified, exclude matching endpoints
   if (exclude) {
     return !exclude.some((entry) => {
-      const parsed = parseEndpointString(entry);
+      const parsed = parseOpenApiEndpoint(entry);
       if (!parsed) return false;
       return `${parsed.method} ${parsed.path}` === endpointKey;
     });
@@ -180,8 +236,6 @@ async function processOpenApiFile(
   parentSlug: string = "",
 ): Promise<OpenApiRoute[]> {
   const routes: OpenApiRoute[] = [];
-  const CWD = process.cwd();
-  const DOCS_DIR = path.join(CWD, "src/content/docs");
 
   // Extract file path and filter options
   let openApiPath: string;
@@ -232,15 +286,7 @@ async function processOpenApiFile(
         continue;
       }
 
-      // Generate slug from path and method (guaranteed to be unique)
-      // e.g., "/burgers" + "get" -> "burgers-get"
-      const pathSlug = pathStr
-        .replace(/^\//, "") // Remove leading slash
-        .replace(/\//g, "-") // Replace slashes with hyphens
-        .replace(/\{[^}]+\}/g, "param"); // Replace path params like {id} with "param"
-
-      const methodSlug = slugify(method);
-      const endpointSlug = pathSlug ? `${pathSlug}-${methodSlug}` : methodSlug;
+      const endpointSlug = buildOpenApiEndpointSlug(pathStr, method);
       const fullSlug = parentSlug
         ? `${parentSlug}/${endpointSlug}`
         : endpointSlug;
@@ -277,15 +323,17 @@ async function processMenuItem(
 
   // Process pages if they exist (pages array can contain pages and groups)
   if (submenu.pages) {
-    submenu.pages.forEach((item) => {
+    for (const item of submenu.pages) {
       if (typeof item === "string" || "page" in item) {
-        routes.push(processPageItem(item as NavPageItem, currentPrefix, docs));
+        routes.push(processPageItem(item, currentPrefix, docs));
       } else if ("group" in item) {
         routes = routes.concat(
-          processGroup(item as NavGroup, currentPrefix, docs),
+          await processGroup(item as NavGroup, currentPrefix, docs),
         );
+      } else if ("openapi" in item) {
+        routes.push(await processOpenApiPageItem(item, currentPrefix));
       }
-    });
+    }
   }
 
   // Process OpenAPI file if it exists
@@ -300,6 +348,31 @@ async function processMenuItem(
   return routes;
 }
 
+function assertUniqueRouteSlugs(routes: Route[]): void {
+  const seenBySlug = new Map<string, Route>();
+
+  for (const route of routes) {
+    const existing = seenBySlug.get(route.slug);
+    if (!existing) {
+      seenBySlug.set(route.slug, route);
+      continue;
+    }
+
+    const existingLabel =
+      existing.type === "mdx"
+        ? `mdx:${existing.filePath}`
+        : `openapi:${existing.filePath}:${existing.openApiMethod.toUpperCase()} ${existing.openApiPath}`;
+    const candidateLabel =
+      route.type === "mdx"
+        ? `mdx:${route.filePath}`
+        : `openapi:${route.filePath}:${route.openApiMethod.toUpperCase()} ${route.openApiPath}`;
+
+    throw new Error(
+      `Duplicate route slug "${route.slug}" generated by "${existingLabel}" and "${candidateLabel}".`,
+    );
+  }
+}
+
 export async function getAllRoutes(): Promise<Route[]> {
   // 1. Get the validated config directly
   const config = await getConfig();
@@ -314,13 +387,15 @@ export async function getAllRoutes(): Promise<Route[]> {
   // We use the XOR guarantee from validateNavigation (only one key exists)
   if (navigation.pages) {
     // Case 1: Pages array at the top level (can contain pages and groups)
-    navigation.pages.forEach((item) => {
+    for (const item of navigation.pages) {
       if (typeof item === "string" || "page" in item) {
-        allRoutes.push(processPageItem(item as NavPageItem, "", docs));
+        allRoutes.push(processPageItem(item, "", docs));
       } else if ("group" in item) {
-        allRoutes = allRoutes.concat(processGroup(item as NavGroup, "", docs));
+        allRoutes = allRoutes.concat(await processGroup(item as NavGroup, "", docs));
+      } else if ("openapi" in item) {
+        allRoutes.push(await processOpenApiPageItem(item, ""));
       }
-    });
+    }
   } else if (navigation.menu) {
     // Case 3: Menu object at the top level
     // Need to await all menu items since processMenuItem is now async
@@ -330,5 +405,6 @@ export async function getAllRoutes(): Promise<Route[]> {
     }
   }
 
+  assertUniqueRouteSlugs(allRoutes);
   return allRoutes;
 }

package/template/src/lib/static-asset-url.ts

@@ -0,0 +1,62 @@
+type AssetsPrefixValue = string | Record<string, string> | undefined;
+
+function normalizePrefix(value: string): string {
+  const normalized = value.trim().replace(/\/+$/, "");
+  if (!normalized) return normalized;
+  if (hasProtocol(normalized) || normalized.startsWith("//")) {
+    return normalized;
+  }
+  if (normalized.startsWith("/")) {
+    return normalized;
+  }
+  return `https://${normalized}`;
+}
+
+function resolveAssetsPrefix(value: AssetsPrefixValue): string | null {
+  if (typeof value === "string" && value.trim().length > 0) {
+    return normalizePrefix(value);
+  }
+
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  const fallback = value.fallback;
+  if (typeof fallback === "string" && fallback.trim().length > 0) {
+    return normalizePrefix(fallback);
+  }
+
+  for (const candidate of Object.values(value)) {
+    if (typeof candidate === "string" && candidate.trim().length > 0) {
+      return normalizePrefix(candidate);
+    }
+  }
+
+  return null;
+}
+
+function hasProtocol(url: string): boolean {
+  return /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(url);
+}
+
+export function resolveStaticAssetUrl(rawPath: string): string {
+  const value = rawPath.trim();
+  if (!value) return value;
+
+  if (hasProtocol(value) || value.startsWith("//")) {
+    return value;
+  }
+
+  const parsed = new URL(value, "https://radiant.invalid");
+  const normalizedPathname = parsed.pathname.startsWith("/")
+    ? parsed.pathname
+    : `/${parsed.pathname}`;
+
+  const prefix = resolveAssetsPrefix(import.meta.env.ASSETS_PREFIX);
+  if (!prefix) {
+    return `${normalizedPathname}${parsed.search}${parsed.hash}`;
+  }
+
+  const normalizedPrefixPath = `${prefix}/${normalizedPathname.replace(/^\/+/, "")}`;
+  return `${normalizedPrefixPath}${parsed.search}${parsed.hash}`;
+}

package/template/src/lib/utils.ts

@@ -79,3 +79,51 @@ export function buildMdxPageHref(args: {
     ? `/${normalizedGroupSlug}/${pageSlug}`
     : `/${pageSlug}`;
 }
+
+export function parseOpenApiEndpoint(
+  endpointStr: string,
+): { method: string; path: string } | null {
+  const trimmed = endpointStr.trim();
+  const parts = trimmed.split(/\s+/);
+
+  if (parts.length !== 2) {
+    return null;
+  }
+
+  const method = parts[0].toUpperCase();
+  let openApiPath = parts[1];
+
+  if (!openApiPath.startsWith("/")) {
+    openApiPath = `/${openApiPath}`;
+  }
+
+  return {
+    method,
+    path: openApiPath.toLowerCase(),
+  };
+}
+
+export function buildOpenApiEndpointSlug(pathStr: string, method: string): string {
+  const normalizedPath = pathStr.startsWith("/") ? pathStr : `/${pathStr}`;
+  const pathSlug = normalizedPath
+    .replace(/^\//, "")
+    .replace(/\//g, "-")
+    .replace(/\{[^}]+\}/g, "param");
+  const methodSlug = slugify(method);
+  return pathSlug ? `${pathSlug}-${methodSlug}` : methodSlug;
+}
+
+export function buildOpenApiEndpointHref(args: {
+  path: string;
+  method: string;
+  groupSlug?: string;
+}): string {
+  const endpointSlug = buildOpenApiEndpointSlug(args.path, args.method);
+  const normalizedGroupSlug = (args.groupSlug || "")
+    .replace(/^\/+/, "")
+    .replace(/\/+$/, "");
+
+  return normalizedGroupSlug
+    ? `/${normalizedGroupSlug}/${endpointSlug}`
+    : `/${endpointSlug}`;
+}