Improve the header of the api doc

Author: Sytten

.vitepress/components/OASpecHeader.vue

@@ -0,0 +1,48 @@
+<script setup lang="ts">
+import { computed } from "vue";
+
+const props = defineProps<{
+  operation: { summary: string; operationId: string };
+  method: string;
+  path: string;
+}>();
+
+const text = computed(() => {
+  return `${props.method.toUpperCase()} ${props.path}`;
+});
+
+const id = computed(() => {
+  return props.operation.operationId;
+});
+
+const summary = computed(() => {
+  if (props.operation.summary.startsWith(props.method.toUpperCase())) {
+    return undefined;
+  }
+  return props.operation.summary;
+});
+</script>
+
+<template>
+  <div class="flex flex-col">
+    <h1 :id="id">
+      <a
+        class="header-anchor"
+        :href="`#${id}`"
+        :aria-label="`Permalink to ${text}`"
+        >&#8203;</a
+      >
+      {{ text }}
+    </h1>
+    <p v-if="summary">{{ summary }}</p>
+  </div>
+</template>
+
+<style scoped>
+.oaspec-header {
+  font-family: var(--vp-font-family-mono);
+  font-size: 0.9rem;
+  font-weight: 600;
+  color: var(--vp-c-text-1);
+}
+</style>

.vitepress/theme/index.mts

@@ -6,13 +6,15 @@ import "./custom.css";
 import { data } from "../data/openapi.data.mjs";
 import ProContainer from "../components/Pro.vue";
 import VideoContainer from "../components/Video.vue";
+import OASpecHeader from "../components/OASpecHeader.vue";
 import type { Theme } from "vitepress";
 
 export default {
   extends: DefaultTheme,
   enhanceApp(ctx) {
     ctx.app.component("ProContainer", ProContainer);
     ctx.app.component("VideoContainer", VideoContainer);
+    ctx.app.component("OASpecHeader", OASpecHeader);
 
     useOpenapi({
       spec: data,

package.json

@@ -28,7 +28,7 @@
     "eslint": "9.28.0",
     "typescript": "5.6.2",
     "vitepress": "1.2.2",
-    "vitepress-openapi": "0.0.3-alpha.83",
+    "vitepress-openapi": "0.1.13",
     "vitepress-plugin-llms": "1.5.1",
     "vue": "3.5.16"
   }

pnpm-lock.yaml

@@ -4,4 +4,11 @@ outline: [1, 1]
 title: API
 ---
 
-<OASpec hide-branding />
+<OASpec
+  :tags='["api"]'
+  hide-branding
+>
+  <template #header="header">
+    <OASpecHeader :operation="header.operation" :method="header.method" :path="header.path" />
+  </template>
+</OASpec>