docs: add api docs

.github/workflows/deploy.yml

@@ -2,6 +2,7 @@ name: Deploy to remote
 on: [push, workflow_dispatch]
 jobs:
   build:
+    name: Build and Deploy
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -16,6 +17,14 @@ jobs:
         run: |
           npm install
           npm run docs:build
+      - name: Build API docs
+        run: |
+          cd dev/api
+          npm install
+          npm run op:build
+          npm run docs:build
+          cp -r .vitepress/dist/ ../../.vitepress/dist/api
+          cd ../../
       - name: Setup SSH
         uses: webfactory/ssh-agent@v0.7.0
         with:

dev/api/.gitignore

@@ -0,0 +1,7 @@
+spec/generated/
+ops/
+openapitools.json
+node_modules/
+.vitepress/dist/
+.vitepress/cache/
+bun.lockb

dev/api/.vitepress/config.mts

@@ -0,0 +1,40 @@
+import { defineConfig } from 'vitepress'
+import { useSidebar, useOpenapi } from 'vitepress-openapi'
+import spec from '../spec/openapi.json' assert { type: "json" }
+
+const sidebar = useSidebar({
+  spec,
+  linkPrefix: '/ops/',
+})
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  base: "/dev/api/",
+  title: "Owu Social API 文档",
+  titleTemplate: ":title - Owu Social API 文档",
+  description: "Owu Social 的 API 文档。",
+  lang: "zh-CN",
+  cleanUrls: true,
+  lastUpdated: true,
+  metaChunk: true, // experimental
+  sitemap: {
+    hostname: "https://scg-docs.owu.one/dev/api"
+  },
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: '首页', link: '/' },
+      { text: '返回', link: 'https://scg-docs.owu.one/' }
+    ],
+
+    sidebar: [
+      { text: '返回食用指南', link: 'https://scg-docs.owu.one/' },
+      { text: '首页', link: '/' },
+      ...sidebar.generateSidebarGroups()
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/owu-one/owu-social-docs' }
+    ]
+  }
+})

dev/api/.vitepress/theme/index.ts

@@ -0,0 +1,23 @@
+// https://vitepress.dev/guide/custom-theme
+// import { h } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+// import './style.css'
+import { theme, useOpenapi } from 'vitepress-openapi'
+import 'vitepress-openapi/dist/style.css'
+
+import spec from '../../spec/openapi.json' assert { type: 'json' }
+
+export default {
+  extends: DefaultTheme,
+  // Layout: () => {
+  //   return h(DefaultTheme.Layout, null, {
+  //     // https://vitepress.dev/guide/extending-default-theme#layout-slots
+  //   })
+  // },
+  enhanceApp({ app, router, siteData }) {
+    const openapi = useOpenapi({ spec })
+    app.provide('openapi', openapi)
+    theme.enhanceApp({ app })
+  }
+} satisfies Theme

dev/api/.vitepress/theme/style.css

@@ -0,0 +1,139 @@
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/**
+ * Colors
+ *
+ * Each colors have exact same color scale system with 3 levels of solid
+ * colors with different brightness, and 1 soft color.
+ * 
+ * - `XXX-1`: The most solid color used mainly for colored text. It must
+ *   satisfy the contrast ratio against when used on top of `XXX-soft`.
+ *
+ * - `XXX-2`: The color used mainly for hover state of the button.
+ *
+ * - `XXX-3`: The color for solid background, such as bg color of the button.
+ *   It must satisfy the contrast ratio with pure white (#ffffff) text on
+ *   top of it.
+ *
+ * - `XXX-soft`: The color used for subtle background such as custom container
+ *   or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
+ *   on top of it.
+ *
+ *   The soft color must be semi transparent alpha channel. This is crucial
+ *   because it allows adding multiple "soft" colors on top of each other
+ *   to create a accent, such as when having inline code block inside
+ *   custom containers.
+ *
+ * - `default`: The color used purely for subtle indication without any
+ *   special meanings attched to it such as bg color for menu hover state.
+ *
+ * - `brand`: Used for primary brand colors, such as link text, button with
+ *   brand theme, etc.
+ *
+ * - `tip`: Used to indicate useful information. The default theme uses the
+ *   brand color for this by default.
+ *
+ * - `warning`: Used to indicate warning to the users. Used in custom
+ *   container, badges, etc.
+ *
+ * - `danger`: Used to show error, or dangerous message to the users. Used
+ *   in custom container, badges, etc.
+ * -------------------------------------------------------------------------- */
+
+ :root {
+  --vp-c-default-1: var(--vp-c-gray-1);
+  --vp-c-default-2: var(--vp-c-gray-2);
+  --vp-c-default-3: var(--vp-c-gray-3);
+  --vp-c-default-soft: var(--vp-c-gray-soft);
+
+  --vp-c-brand-1: var(--vp-c-indigo-1);
+  --vp-c-brand-2: var(--vp-c-indigo-2);
+  --vp-c-brand-3: var(--vp-c-indigo-3);
+  --vp-c-brand-soft: var(--vp-c-indigo-soft);
+
+  --vp-c-tip-1: var(--vp-c-brand-1);
+  --vp-c-tip-2: var(--vp-c-brand-2);
+  --vp-c-tip-3: var(--vp-c-brand-3);
+  --vp-c-tip-soft: var(--vp-c-brand-soft);
+
+  --vp-c-warning-1: var(--vp-c-yellow-1);
+  --vp-c-warning-2: var(--vp-c-yellow-2);
+  --vp-c-warning-3: var(--vp-c-yellow-3);
+  --vp-c-warning-soft: var(--vp-c-yellow-soft);
+
+  --vp-c-danger-1: var(--vp-c-red-1);
+  --vp-c-danger-2: var(--vp-c-red-2);
+  --vp-c-danger-3: var(--vp-c-red-3);
+  --vp-c-danger-soft: var(--vp-c-red-soft);
+}
+
+/**
+ * Component: Button
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-button-brand-border: transparent;
+  --vp-button-brand-text: var(--vp-c-white);
+  --vp-button-brand-bg: var(--vp-c-brand-3);
+  --vp-button-brand-hover-border: transparent;
+  --vp-button-brand-hover-text: var(--vp-c-white);
+  --vp-button-brand-hover-bg: var(--vp-c-brand-2);
+  --vp-button-brand-active-border: transparent;
+  --vp-button-brand-active-text: var(--vp-c-white);
+  --vp-button-brand-active-bg: var(--vp-c-brand-1);
+}
+
+/**
+ * Component: Home
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    120deg,
+    #bd34fe 30%,
+    #41d1ff
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    #bd34fe 50%,
+    #47caff 50%
+  );
+  --vp-home-hero-image-filter: blur(44px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(68px);
+  }
+}
+
+/**
+ * Component: Custom Block
+ * -------------------------------------------------------------------------- */
+
+:root {
+  --vp-custom-block-tip-border: transparent;
+  --vp-custom-block-tip-text: var(--vp-c-text-1);
+  --vp-custom-block-tip-bg: var(--vp-c-brand-soft);
+  --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
+}
+
+/**
+ * Component: Algolia
+ * -------------------------------------------------------------------------- */
+
+.DocSearch {
+  --docsearch-primary-color: var(--vp-c-brand-1) !important;
+}
+

dev/api/index.md

@@ -0,0 +1,17 @@
+---
+title: API
+description: Owu Social 的 API 文档。
+---
+
+::: warning 注意
+特定于端点的文档（即侧边栏中的文档）使用的主题仍在开发中，样式可能有错乱，显示的信息可能不完整。
+目前推荐使用本页的 Swagger UI 来查看 API 文档。
+:::
+
+<OAInfo />
+
+<OAServers />
+
+## Swagger UI
+
+<iframe src="swagger-ui.html" width="100%" height="19400px" frameborder="0"></iframe>

dev/api/package.json

@@ -0,0 +1,19 @@
+{
+  "scripts": {
+    "docs:dev": "vitepress dev .",
+    "docs:build": "vitepress build .",
+    "docs:preview": "vitepress preview .",
+    "api:download": "wget -O ./spec/swagger-original.yaml https://raw.githubusercontent.com/superseriousbusiness/gotosocial/refs/heads/main/docs/api/swagger.yaml",
+    "api:generate": "openapi-generator-cli generate -i ./spec/swagger.yaml -g openapi -o spec/generated && cp spec/generated/openapi.json spec/openapi.json",
+    "op:build": "bun spec/rebuild-op-dir.ts"
+  },
+  "dependencies": {
+    "@openapitools/openapi-generator-cli": "^2.15.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.8.1",
+    "js-yaml": "^4.1.0",
+    "vitepress": "^1.4.1",
+    "vitepress-openapi": "^0.0.3-alpha.44",
+    "vue": "^3.5.12"
+  }
+}