feat(docs): show API routes on overview

This reverts commit c1dc77f6db.

docs/components/api-overview.tsx

@@ -0,0 +1,65 @@
+import Link from "next/link";
+
+import { getOpenAPIOperations } from "@/lib/openapi-operations";
+
+const methodColors: Record<string, string> = {
+  GET: "bg-emerald-100 text-emerald-700",
+  POST: "bg-blue-100 text-blue-700",
+  PUT: "bg-amber-100 text-amber-700",
+  PATCH: "bg-purple-100 text-purple-700",
+  DELETE: "bg-rose-100 text-rose-700",
+};
+
+function MethodBadge({ method }: { method: string }) {
+  const color = methodColors[method] ?? "bg-slate-100 text-slate-700";
+
+  return (
+    <span
+      className={`font-semibold uppercase tracking-wide text-xs px-2 py-1 rounded ${color}`}
+    >
+      {method}
+    </span>
+  );
+}
+
+export function APIOverviewTable() {
+  const operations = getOpenAPIOperations();
+
+  if (operations.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className="not-prose mt-6 overflow-x-auto">
+      <table className="w-full border-separate border-spacing-y-2 text-sm">
+        <thead className="text-left text-muted-foreground">
+          <tr>
+            <th className="px-3 py-2 font-medium">路径</th>
+            <th className="px-3 py-2 font-medium">方法</th>
+            <th className="px-3 py-2 font-medium">摘要</th>
+          </tr>
+        </thead>
+        <tbody>
+          {operations.map((operation) => (
+            <tr
+              key={`${operation.method}-${operation.route}`}
+              className="bg-muted/30"
+            >
+              <td className="px-3 py-2 align-top font-mono">
+                <Link className="hover:underline" href={operation.href}>
+                  {operation.route}
+                </Link>
+              </td>
+              <td className="px-3 py-2 align-top">
+                <MethodBadge method={operation.method} />
+              </td>
+              <td className="px-3 py-2 align-top text-muted-foreground">
+                {operation.summary || "—"}
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}

docs/content/docs/openapi/index.mdx

@@ -2,3 +2,11 @@
 title: API 概览
 description: Open API 接口文档
 ---
+
+import { APIOverviewTable } from "@/components/api-overview";
+
+# 接口列表
+
+以下列表聚合了所有已生成的接口页面，展示对应的路径、请求方法以及摘要，便于快速检索和跳转。
+
+<APIOverviewTable />

docs/lib/openapi-operations.ts

@@ -0,0 +1,68 @@
+import matter from "gray-matter";
+
+import { source } from "@/lib/source";
+
+interface OperationFrontmatter {
+  title?: string;
+  description?: string;
+  _openapi?: {
+    method?: string;
+    route?: string;
+  };
+}
+
+export interface OpenAPIOperation {
+  href: string;
+  method: string;
+  route: string;
+  summary: string;
+}
+
+function parseFrontmatter(content: string): OperationFrontmatter {
+  const result = matter(content);
+
+  return result.data as OperationFrontmatter;
+}
+
+function normalizeSummary(frontmatter: OperationFrontmatter): string {
+  return frontmatter.title ?? frontmatter.description ?? "";
+}
+
+export function getOpenAPIOperations(): OpenAPIOperation[] {
+  return source
+    .getPages()
+    .filter((page) =>
+      page.url.startsWith("/openapi/") && page.url !== "/openapi"
+    )
+    .map((page) => {
+      if (typeof page.data.content !== "string") {
+        return undefined;
+      }
+
+      const frontmatter = parseFrontmatter(page.data.content);
+
+      const method = frontmatter._openapi?.method?.toUpperCase();
+      const route = frontmatter._openapi?.route;
+      const summary = normalizeSummary(frontmatter);
+
+      if (!method || !route) {
+        return undefined;
+      }
+
+      return {
+        href: page.url,
+        method,
+        route,
+        summary,
+      } satisfies OpenAPIOperation;
+    })
+    .filter((operation): operation is OpenAPIOperation => Boolean(operation))
+    .sort((a, b) => {
+      const routeCompare = a.route.localeCompare(b.route);
+      if (routeCompare !== 0) {
+        return routeCompare;
+      }
+
+      return a.method.localeCompare(b.method);
+    });
+}

docs/scripts/generate-docs.ts

@@ -1,10 +1,18 @@
+import { rmSync } from "node:fs";
+
 import { generateFiles } from "fumadocs-openapi";
 import { openapi } from "@/lib/openapi";
 
+const outputDir = "./content/docs/openapi/(generated)";
+
+rmSync(outputDir, { recursive: true, force: true });
+
 void generateFiles({
   input: openapi,
-  output: "./content/docs/openapi/(generated)",
+  output: outputDir,
   // we recommend to enable it
   // make sure your endpoint description doesn't break MDX syntax.
   includeDescription: true,
+  per: "operation",
+  groupBy: "route",
 });

frontend_nuxt/components/BaseTimeline.vue

@@ -1,5 +1,5 @@
 <template>
-  <div class="timeline" :class="{ 'hover-enabled': hover }">
+  <div class="timeline">
     <div class="timeline-item" v-for="(item, idx) in items" :key="idx">
       <div
         class="timeline-icon"
@@ -26,7 +26,6 @@ export default {
   name: 'BaseTimeline',
   props: {
     items: { type: Array, default: () => [] },
-    hover: { type: Boolean, default: false },
   },
 }
 </script>
@@ -46,12 +45,6 @@ export default {
   margin-top: 10px;
 }
 
-.hover-enabled .timeline-item:hover {
-  background-color: var(--menu-selected-background-color);
-  transition: background-color 0.2s;
-  border-radius: 10px;
-}
-
 .timeline-icon {
   position: sticky;
   top: 0;
@@ -95,7 +88,7 @@ export default {
 }
 
 .timeline-item:last-child::before {
-  display: none;
+  bottom: 0px;
 }
 
 .timeline-content {

frontend_nuxt/components/TimelineTagItem.vue

@@ -1,26 +1,16 @@
 <template>
   <div class="timeline-tag-item">
-    <template v-if="mode === 'timeline'">
-      <div class="tags-container">
-        <div class="tags-container-item">
-          <div class="timeline-tag-title">{{ title }}</div>
-          <ArticleTags v-if="tag" :tags="[tag]" />
-        </div>
-        <div v-if="timelineDate" class="timeline-date">{{ timelineDate }}</div>
+    <div class="tags-container">
+      <div class="tags-container-item">
+        <div class="timeline-tag-title">创建了标签</div>
+        <ArticleTags v-if="tag" :tags="[tag]" />
+        <span class="timeline-tag-count" v-if="tag?.count"> x{{ tag.count }}</span>
       </div>
-      <div v-if="hasDescription" class="timeline-snippet">
-        {{ tag?.description }}
-      </div>
-    </template>
-    <template v-else>
-      <span class="timeline-link" :class="{ clickable: isClickable }" @click="handleTagClick">
-        {{ tag?.name }}<span v-if="tag?.count"> x{{ tag.count }}</span>
-      </span>
-      <div v-if="hasDescription" class="timeline-snippet">
-        {{ tag?.description }}
-      </div>
-      <div v-if="summaryDate" class="timeline-date">{{ summaryDate }}</div>
-    </template>
+      <div v-if="timelineDate" class="timeline-date">{{ timelineDate }}</div>
+    </div>
+    <div v-if="hasDescription" class="timeline-snippet">
+      {{ tag?.description }}
+    </div>
   </div>
 </template>
 
@@ -30,15 +20,6 @@ import TimeManager from '~/utils/time'
 
 const props = defineProps({
   item: { type: Object, required: true },
-  mode: {
-    type: String,
-    default: 'timeline',
-    validator: (value) => ['timeline', 'summary'].includes(value),
-  },
-  title: {
-    type: String,
-    default: '创建了标签',
-  },
 })
 
 const emit = defineEmits(['tag-click'])
@@ -95,6 +76,10 @@ const handleTagClick = () => {
   font-weight: 600;
 }
 
+.timeline-tag-count {
+  font-size: 12px;
+}
+
 .timeline-date {
   font-size: 12px;
   color: gray;

frontend_nuxt/pages/users/[id].vue

@@ -112,19 +112,18 @@
                         {{ item.comment.post.title }}
                       </NuxtLink>
                       <template v-if="item.comment.parentComment">
-                        下对
                         <NuxtLink
                           :to="`/posts/${item.comment.post.id}#comment-${item.comment.parentComment.id}`"
-                          class="timeline-link"
+                          class="timeline-comment-link"
                         >
                           {{ stripMarkdownLength(item.comment.parentComment.content, 200) }}
                         </NuxtLink>
-                        回复了
+                        <next class="reply-icon" /> 回复了
                       </template>
                       <template v-else> 下评论了 </template>
                       <NuxtLink
                         :to="`/posts/${item.comment.post.id}#comment-${item.comment.id}`"
-                        class="timeline-link"
+                        class="timeline-comment-link"
                       >
                         {{ stripMarkdownLength(item.comment.content, 200) }}
                       </NuxtLink>
@@ -156,7 +155,7 @@
                 <div class="summary-content" v-if="hotTags.length > 0">
                   <BaseTimeline :items="hotTags">
                     <template #item="{ item }">
-                      <TimelineTagItem :item="item" mode="summary" @tag-click="gotoTag" />
+                      <TimelineTagItem :item="item" />
                     </template>
                   </BaseTimeline>
                 </div>
@@ -670,6 +669,11 @@ watch(selectedTab, async (val) => {
   color: #666;
 }
 
+.reply-icon {
+  color: var(--primary-color);
+  margin-left: 5px;
+}
+
 .profile-page-header-user-info-buttons {
   display: flex;
   flex-direction: row;
@@ -922,8 +926,8 @@ watch(selectedTab, async (val) => {
 
 .timeline-link {
   font-weight: bold;
-  color: var(--primary-color);
   text-decoration: none;
+  color: var(--text-color);
   word-break: break-word;
 }
 
@@ -1014,6 +1018,7 @@ watch(selectedTab, async (val) => {
   color: var(--text-color);
   word-break: break-word;
   text-decoration: underline;
+  margin-left: 5px;
 }
 
 .timeline-comment-link:hover {