feat: 从 FastAPI 导出 openapi.json 并渲染为 API 文档

通过 vitepress-openapi 插件，在 VitePress 文档中实现基于 openapi.json 的 API 文档。
这样实现的 API 文档可以从最新版本的代码库中提取路由信息，继而实现自动集成。
---
同时，通过 Kimi 和 Deepseek 实现并审查了一个对 Google 风格 docstring 的解析函数。
该函数可以从 Google 风格的 docstring 中提取参数文档并按 openapi 规范重新整理它们。
---
增加了 nyahome openapi 命令用来导出 openapi.json。
增加了 task openapi-docs 命令用来准备未来的持续集成。

docs/.vitepress/config.mts

@@ -1,4 +1,12 @@
-import {defineConfig} from 'vitepress'
+import { defineConfig } from 'vitepress'
+import { useSidebar } from 'vitepress-openapi'
+import spec from './theme/openapi.json' with { type: 'json' }
+
+
+const sidebar = useSidebar({
+  spec,
+  linkPrefix: '/dev/api-docs/'
+})
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -7,29 +15,46 @@ export default defineConfig({
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
     nav: [
-      {text: '主页', link: '/'},
-      {text: '使用', link: '/use/start'}
+      { text: '主页', link: '/' },
+      { text: '使用', link: '/use/start' },
+      { text: '开发', link: '/dev/start' },
     ],
 
-    sidebar: [
-      {
+    sidebar: {
+      'use': [{
         text: '使用',
         items: [
-          {text: '开始', link: '/use/start'},
-          {text: '默认行为', link: '/use/default-action'},
-          {text: '用户系统', link: '/use/user-system'},
+          { text: '开始', link: '/use/start' },
+          { text: '默认行为', link: '/use/default_action' },
+          { text: '用户系统', link: '/use/user_system' },
         ]
       },
-      {
-        text: '开发',
-        items: [
-          {text: '后端响应', link: '/dev/backend-response'},
-        ]
-      },
-    ],
+      ],
+
+      'dev': [
+        {
+          text: '开发',
+          items: [
+            { text: '开始', link: '/dev/start' },
+            { text: '后端响应', link: '/dev/backend_response' },
+            { text: '邮件模板', link: '/dev/email_templates' },
+          ]
+        },
+        {
+          text: 'API 文档',
+          items: [
+            { text: 'API', link: '/dev/api-docs/api' },
+            ...sidebar.generateSidebarGroups({}),
+          ]
+        },]
+    },
 
     socialLinks: [
-      {icon: 'github', link: 'https://github.com/vuejs/vitepress'}
+      { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
     ]
+  },
+
+  sitemap: {
+    hostname: 'https://docs.nyahome.cn'
   }
 })

docs/.vitepress/theme/custom.css

@@ -1,4 +1,51 @@
 :root {
     --vp-c-brand-1: #64ffc4;
     --vp-c-brand-2: #9354ff;
+}
+
+/* ===== 简约滚动条美化 ===== */
+
+/* 适用于 Webkit 内核（Chrome/Edge/Safari） */
+::-webkit-scrollbar {
+    width: 6px;
+    /* 垂直滚动条宽度 */
+    height: 6px;
+    /* 水平滚动条高度 */
+}
+
+::-webkit-scrollbar-track {
+    background: transparent;
+    /* 轨道透明，极简 */
+}
+
+::-webkit-scrollbar-thumb {
+    background: rgba(255, 255, 255, 0.15);
+    /* 滑块半透明灰 */
+    border-radius: 3px;
+    /* 小圆角 */
+}
+
+::-webkit-scrollbar-thumb:hover {
+    background: rgba(255, 255, 255, 0.25);
+    /* 悬停稍微深一点 */
+}
+
+/* Firefox 兼容 */
+* {
+    scrollbar-width: thin;
+    scrollbar-color: rgba(255, 255, 255, 0.15) transparent;
+}
+
+/* vitepress-openapi */
+div.vitepress-openapi {
+    border: 1px solid #64ffc4;
+    border-radius: 6px;
+    margin: 48px auto 0;
+    padding: 6px 20px;
+
+    text-align: center;
+}
+
+div.vitepress-openapi p {
+    line-height: 8px;
 }

docs/.vitepress/theme/index.ts

@@ -1,5 +1,26 @@
 import DefaultTheme from 'vitepress/theme'
+import { theme, useOpenapi } from 'vitepress-openapi/client'
+import 'vitepress-openapi/dist/style.css'
 // @ts-ignore
 import './custom.css'
+import { Theme } from 'vitepress'
 
-export default DefaultTheme
+import spec from './openapi.json' with { type: 'json' }
+
+export default {
+  extends: DefaultTheme,
+  async enhanceApp({ app }) {
+    useOpenapi({
+      spec,
+      config: {
+        codeSamples: {
+          defaultLang: 'python',
+        },
+        server: {
+          allowCustomServer: true,
+        },
+      }
+    })
+    theme.enhanceApp({ app })
+  }
+} satisfies Theme