feat: api documentation (#603)

* feat: api documentation

* fix

* fix

* Apply suggestions from code review

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: tac0turtle <[email protected]>

Author: 3 people

.vitepress/config.ts

@@ -1,11 +1,19 @@
 import { withMermaid } from "vitepress-plugin-mermaid";
+import { useSidebar } from 'vitepress-openapi'
+import spec from '../src/openapi-rpc.json' with { type: 'json' }
 
 const telegramSVG = ` <svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
 <path fill-rule="evenodd" clip-rule="evenodd" d="M24 12C24 18.6274 18.6274 24 12 24C5.37258 24 0 18.6274 0 12C0 5.37258 5.37258 0 12 0C18.6274 0 24 5.37258 24 12ZM12.43 8.85893C11.2628 9.3444 8.93014 10.3492 5.43189 11.8733C4.86383 12.0992 4.56626 12.3202 4.53917 12.5363C4.49339 12.9015 4.95071 13.0453 5.57347 13.2411C5.65818 13.2678 5.74595 13.2954 5.83594 13.3246C6.44864 13.5238 7.27283 13.7568 7.70129 13.766C8.08994 13.7744 8.52373 13.6142 9.00264 13.2853C12.2712 11.079 13.9584 9.96381 14.0643 9.93977C14.139 9.92281 14.2426 9.90148 14.3128 9.96385C14.3829 10.0262 14.376 10.1443 14.3686 10.176C14.3233 10.3691 12.5281 12.0381 11.5991 12.9018C11.3095 13.171 11.1041 13.362 11.0621 13.4056C10.968 13.5033 10.8721 13.5958 10.78 13.6846C10.2108 14.2333 9.78391 14.6448 10.8036 15.3168C11.2936 15.6397 11.6858 15.9067 12.077 16.1731C12.5042 16.4641 12.9303 16.7543 13.4816 17.1157C13.6221 17.2077 13.7562 17.3034 13.8869 17.3965C14.3841 17.751 14.8307 18.0694 15.3826 18.0186C15.7032 17.9891 16.0345 17.6876 16.2027 16.7884C16.6002 14.6631 17.3816 10.0585 17.5622 8.16097C17.578 7.99473 17.5581 7.78197 17.5422 7.68857C17.5262 7.59518 17.4928 7.46211 17.3714 7.3636C17.2276 7.24694 17.0056 7.22234 16.9064 7.22408C16.455 7.23203 15.7626 7.47282 12.43 8.85893Z" fill="currentColor"/>
 </svg>`;
 
 const { BASE: base = "/" } = process.env;
 
+const sidebar = useSidebar({
+    spec,
+    // Optionally, you can specify a link prefix for all generated sidebar items. Default is `/operations/`.
+    linkPrefix: '/api/',
+})
+
 // https://vitepress.dev/reference/site-config
 export default withMermaid({
   lang: "en-US",
@@ -162,6 +170,7 @@ function nav() {
     { text: "Learn", link: "/learn/about" },
     { text: "How To Guides", link: "/guides/quick-start" },
     { text: "Blog", link: "/blog/overview" },
+    { text: "API Documentation", link: "/api" },
   ];
 }
 
@@ -306,5 +315,18 @@ function sidebarHome() {
       collapsed: true,
       items: [{ text: "Overview", link: "/blog/overview" }],
     },
+    {
+      text: "API Documentation",
+      collapsed: true,
+      items: [
+        {
+          text: "Introduction",
+          link: "/api",
+        },
+        ...sidebar.generateSidebarGroups({
+            linkPrefix: "/api/operationsByTags/"
+          })
+      ]
+    },
   ];
 }

.vitepress/theme/index.ts

@@ -2,6 +2,8 @@
 import { h } from 'vue'
 import Theme from 'vitepress/theme'
 import './style.css'
+import { theme } from 'vitepress-openapi/client'
+import 'vitepress-openapi/dist/style.css'
 
 export default {
   extends: Theme,
@@ -11,6 +13,6 @@ export default {
     })
   },
   enhanceApp({ app, router, siteData }) {
-    // ...
+    theme.enhanceApp({ app, router, siteData })
   }
 }

api/index.md

@@ -0,0 +1,11 @@
+---
+aside: false
+outline: false
+title: API Introduction
+---
+
+<script setup>
+import spec from '../src/openapi-rpc.json'
+</script>
+
+<OAIntroduction :spec="spec" />

api/operationsByTags/[operationId].md

@@ -0,0 +1,16 @@
+---
+aside: false
+outline: false
+title: API Operation Details
+---
+
+<script setup lang="ts">
+import { useRoute } from 'vitepress'
+import spec from '../../src/openapi-rpc.json'
+
+const route = useRoute()
+
+const operationId = route.data.params.operationId
+</script>
+
+<OAOperation :spec="spec" :operationId="operationId" />

api/operationsByTags/[operationId].paths.js

@@ -0,0 +1,17 @@
+import { usePaths } from 'vitepress-openapi'
+import spec from '../../src/openapi-rpc.json' with {type: 'json'}
+
+export default {
+    paths() {
+        return usePaths({ spec })
+            .getPathsByVerbs()
+            .map(({ operationId, summary }) => {
+                return {
+                    params: {
+                        operationId,
+                        pageTitle: `${summary} - vitepress-openapi`,
+                    },
+                }
+            })
+    },
+}

package.json

@@ -13,5 +13,8 @@
     "vitepress": "^1.5.0",
     "vitepress-plugin-mermaid": "^2.0.17"
   },
+  "dependencies": {
+    "vitepress-openapi": "^0.1.3"
+  },
   "type": "module"
 }