feat(openapi): add openapi document

.vitepress/config.mts

@@ -1,4 +1,12 @@
-import { defineConfig, type DefaultTheme } from 'vitepress'
+import { defineConfig, type DefaultTheme } from 'vitepress';
+import { useSidebar } from 'vitepress-openapi';
+import spec from '../docs/openapi/openapi.json' with { type: 'json' };
+
+const sidebar = useSidebar({
+  spec,
+  // Optionally, you can specify a link prefix for all generated sidebar items.
+  linkPrefix: '/operations/',
+})
 
 export default defineConfig({
   title: "WebhookX",
@@ -30,7 +38,7 @@ export default defineConfig({
 
     sidebar: {
       '/docs/': { base: '', items: sidebarDocs() },
-      '/blog/': { base: '/blog/', items: sidebarBlog() }
+      '/blog/': { base: '/blog/', items: sidebarBlog() },
     },
 
 
@@ -39,7 +47,18 @@ export default defineConfig({
       { icon: 'x', link: 'https://x.com/WebhookX' },
       { icon: 'slack', link: 'https://join.slack.com/t/webhookx/shared_invite/zt-2o4b6hv45-mWm6_WUcQP9qEf1nOxhrrg' },
     ]
-  }
+  },
+  /** Give each dynamic page its own <title> */
+  transformPageData(pageData) {
+    // params returned from [*].paths.js|ts are available here
+    const pageTitle = pageData.params?.pageTitle;
+
+    if (pageTitle) {
+      pageData.title = pageTitle;
+      pageData.frontmatter ??= {};
+      pageData.frontmatter.title = pageTitle;
+    }
+  },
 })
 
 
@@ -66,11 +85,24 @@ function sidebarDocs(): DefaultTheme.SidebarItem[] {
       ]
     },
     {
-      text: "Admin API",
+      text: 'OpenAPI',
       collapsed: false,
       items: [
-        { text: 'Overview', link: 'docs/admin/overview' },
-      ]
+        {
+          text: 'Overview',
+          link: '/docs/openapi/overview',
+        },
+        ...sidebar.generateSidebarGroups({
+          linkPrefix: '/docs/openapi/operations/',
+        }).map((group) => ({
+          ...group,
+          collapsed: true
+        })),
+        {
+          text: 'One Page',
+          link: '/docs/openapi/one-page',
+        },
+      ],
     },
     {
       text: "Plugins",
@@ -95,7 +127,6 @@ function sidebarDocs(): DefaultTheme.SidebarItem[] {
       text: "References",
       items: [
         { text: 'CLI', link: 'docs/cli' },
-        { text: 'OpenAPI', link: 'https://github.com/webhookx-io/webhookx/blob/main/openapi.yml' },
         { text: 'Release Notes', link: 'https://github.com/webhookx-io/webhookx/releases' },
       ]
     },
@@ -116,4 +147,3 @@ function sidebarBlog(): DefaultTheme.SidebarItem[] {
     },
   ]
 }
-

.vitepress/theme/index.ts

@@ -0,0 +1,18 @@
+import type { Theme } from 'vitepress';
+import DefaultTheme from 'vitepress/theme';
+
+import { theme, useOpenapi } from 'vitepress-openapi/client';
+import 'vitepress-openapi/dist/style.css';
+import spec from '../../docs/openapi/openapi.json' with { type: 'json' };
+
+export default {
+  ...DefaultTheme,
+  async enhanceApp({ app, router, siteData }) {
+    const openapi = useOpenapi({
+      spec: spec,
+      config: {},
+    });
+
+    theme.enhanceApp({ app, openapi });
+  },
+} satisfies Theme;

Makefile

@@ -9,3 +9,7 @@ build:
 .PHONY: preview
 preview:
 	npm run docs:preview
+
+.PHONY: oy2j
+oy2j:
+	npx openapi-format https://raw.githubusercontent.com/webhookx-io/webhookx/refs/heads/main/openapi.yml -o ./docs/openapi/openapi.json

docs/openapi/one-page.md

@@ -0,0 +1,6 @@
+---
+aside: false
+title: vitepress-openapi
+---
+
+<OASpec />