vitepress-openapi 0.1.13 → 0.1.15

package/src/components/Sample/OACodeSamples.vue

@@ -1,63 +1,109 @@
 <script setup lang="ts">
 import type { OperationData } from '@/lib/operation/operationData'
+import type { LanguageConfig } from '../../composables/useTheme'
 import { OPERATION_DATA_KEY } from '@/lib/operation/operationData'
-import { computed, inject, ref, watch } from 'vue'
+import { inject, ref, watch } from 'vue'
+import { useShiki } from '../../composables/useShiki'
 import { useTheme } from '../../composables/useTheme'
 import OACodeBlock from '../Common/OACodeBlock.vue'
 
+type Sample = LanguageConfig & {
+  key: string
+  tabId: string
+  highlighter: string
+  source: string
+}
+
 const props = defineProps({
   operationId: {
     type: String,
     required: true,
   },
-  codeSamples: {
-    type: Object,
-    default: () => ({}),
-  },
 })
 
 const operationData = inject(OPERATION_DATA_KEY) as OperationData
 
 const themeConfig = useTheme()
 
-const availableLanguages = themeConfig.getCodeSamplesAvailableLanguages()
+const shiki = useShiki()
 
-const configuredLanguages = themeConfig.getCodeSamplesLangs()
+const availableLanguages = themeConfig.getCodeSamplesAvailableLanguages()
 
 const generator = themeConfig.getCodeSamplesGenerator()
 
-const samples = ref(typeof props.codeSamples === 'object' && !Array.isArray(props.codeSamples)
-  ? Object.entries(props.codeSamples).map(([lang, source]) => ({
-      lang,
-      source,
-    }))
-  : props.codeSamples)
+const samples = ref<Sample[]>([])
+
+const activeSampleKey = ref('')
 
-const defaultLang = computed(() => {
-  const defaultValue = themeConfig.getCodeSamplesDefaultLang()
+const radioGroupName = `group-${props.operationId}`
 
-  if (!samples.value?.find(sample => sample.lang === defaultValue)) {
-    return samples.value?.[0]?.lang
+watch(operationData.playground.request, async (playgroundRequest, _, onInvalidate) => {
+  let cancelled = false
+  onInvalidate(() => {
+    cancelled = true
+  })
+
+  if (!availableLanguages || !generator) {
+    return
   }
 
-  return defaultValue
-})
+  const nextSamples = await Promise.all(
+    availableLanguages.map(async (langConfig) => {
+      const { lang, target, client, highlighter } = langConfig
+      const key = [lang, target, client]
+        .filter(Boolean)
+        .join('-')
+      const tabId = `tab-${props.operationId}-${key}`
 
-const activeSample = ref(samples.value?.find(sample => sample.lang === defaultLang.value)?.lang)
+      try {
+        const source = await generator(langConfig, playgroundRequest)
+        if (!source) {
+          throw new Error('Code generator returned empty result.')
+        }
 
-watch(operationData.playground.request, async (request) => {
-  if (!availableLanguages || !configuredLanguages || !generator) {
+        return {
+          ...langConfig,
+          key,
+          tabId,
+          highlighter: highlighter || 'plain',
+          source,
+        }
+      }
+      catch (error) {
+        console.error(`Failed to generate code sample for '${lang}'`, { langConfig, error })
+        return {
+          ...langConfig,
+          key,
+          tabId,
+          highlighter: 'shell',
+          source: `// Failed to generate sample.\n// Please check the console for details.`,
+        }
+      }
+    }),
+  )
+
+  // Guard against stale data due to rapid updates of `operationData.playground.request`
+  if (cancelled) {
     return
   }
 
-  samples.value = await Promise.all(
-    availableLanguages
-      .filter(availableLanguage => configuredLanguages.includes(availableLanguage.lang))
-      .map(async availableLanguage => ({
-        ...availableLanguage,
-        source: await generator(availableLanguage.lang, request),
-      })),
-  )
+  // Preload all highlighter languages
+  const uniqueHighlighters = [...new Set(nextSamples.map(s => s.highlighter).filter(Boolean))]
+  await Promise.all(uniqueHighlighters.map(lang => shiki.ensureLanguage(lang)))
+
+  if (cancelled) {
+    return
+  }
+
+  samples.value = nextSamples
+
+  if (!activeSampleKey.value || !samples.value.some(s => s.key === activeSampleKey.value)) {
+    const defaultLang = themeConfig.getCodeSamplesDefaultLang()
+    const defaultSample = samples.value.find(s => s.lang === defaultLang) || samples.value[0]
+    if (defaultSample) {
+      activeSampleKey.value = defaultSample.key
+    }
+  }
 }, {
   deep: true,
   immediate: true,
@@ -71,30 +117,30 @@ watch(operationData.playground.request, async (request) => {
       class="vp-code-group vp-adaptive-theme mt-0"
     >
       <div class="tabs !m-0">
-        <template v-for="sample in samples" :key="sample.lang">
+        <template v-for="sample in samples" :key="sample.key">
           <input
-            :id="`tab-${props.operationId}-${sample.lang}`"
+            :id="sample.tabId"
             type="radio"
-            :name="`group-${props.operationId}`"
-            :checked="sample.lang === defaultLang"
-            @change="activeSample = sample.lang"
+            :name="radioGroupName"
+            :checked="activeSampleKey === sample.key"
+            @change="activeSampleKey = sample.key"
           >
           <label
-            :for="`tab-${props.operationId}-${sample.lang}`"
+            :for="sample.tabId"
             :data-title="sample.icon"
-          >{{ sample.label || sample.lang }}</label>
+          >{{ sample.label }}</label>
         </template>
       </div>
 
       <div class="blocks">
         <OACodeBlock
           v-for="sample in samples"
-          :key="sample.lang"
+          :key="sample.key"
           :code="sample.source"
           :lang="sample.highlighter"
           :label="sample.label"
-          :active="activeSample === sample.lang"
-          :class="{ active: sample.lang === defaultLang }"
+          :active="activeSampleKey === sample.key"
+          :class="{ active: activeSampleKey === sample.key }"
           class="!m-0"
         />
       </div>

package/src/composables/useShiki.ts

@@ -1,26 +1,27 @@
 import type { HighlighterCore } from 'shiki/core'
-import bash from '@shikijs/langs/bash'
-import js from '@shikijs/langs/javascript'
-import json from '@shikijs/langs/json'
-import markdown from '@shikijs/langs/markdown'
-import php from '@shikijs/langs/php'
-import python from '@shikijs/langs/python'
-import ts from '@shikijs/langs/typescript'
-import xml from '@shikijs/langs/xml'
+import type { BundledLanguage } from 'shiki/langs'
 import { createHighlighterCore } from 'shiki/core'
 import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'
+import { bundledLanguages as highlighterImports } from 'shiki/langs'
 import { ref } from 'vue'
 import { useTheme } from './useTheme'
 
-const langs = [js, ts, markdown, json, xml, python, bash, php]
+// Core highlighters always loaded for response body highlighting (not shown in code samples UI)
+const CORE_HIGHLIGHTERS: BundledLanguage[] = ['json', 'xml', 'markdown']
 
 let shiki: HighlighterCore | null = null
 let initPromise: Promise<void> | null = null
 
+// Track in-flight language loads to avoid duplicate requests
+const languageLoadPromises = new Map<string, Promise<boolean>>()
+
 const loading = ref(true)
-const themeConfig = useTheme()
 
 export function useShiki() {
+  /**
+   * Initialize Shiki with core highlighters only (json, xml, markdown).
+   * Additional languages are loaded on-demand via ensureLanguage().
+   */
   function init(): Promise<void> {
     if (initPromise) {
       return initPromise
@@ -33,17 +34,39 @@ export function useShiki() {
           return
         }
 
+        const themeConfig = useTheme()
+
+        // Load only core highlighters during init
+        const coreLangModules = await Promise.all(
+          CORE_HIGHLIGHTERS.map(async (lang) => {
+            const importer = highlighterImports[lang]
+            if (!importer) {
+              return []
+            }
+            try {
+              const mod = await importer()
+              return mod.default
+            } catch {
+              return []
+            }
+          }),
+        )
+
         shiki = await createHighlighterCore({
           themes: [
             themeConfig.getHighlighterTheme()?.light,
             themeConfig.getHighlighterTheme()?.dark,
           ],
-          langs,
+          langs: coreLangModules.filter(Boolean).flat(),
           engine: createJavaScriptRegexEngine({
             target: 'ES2018',
           }),
         })
 
+        if (!shiki) {
+          throw new Error('Failed to create Shiki highlighter')
+        }
+
         loading.value = false
       } catch (error) {
         initPromise = null
@@ -54,10 +77,67 @@ export function useShiki() {
     return initPromise
   }
 
+  /**
+   * Ensure a language is loaded. Loads it on-demand if not already available.
+   * Returns true if the language is ready, false if it couldn't be loaded.
+   */
+  async function ensureLanguage(lang: string): Promise<boolean> {
+    // Make sure shiki is initialized first
+    try {
+      await init()
+    } catch (e) {
+      console.error('Failed to initialize Shiki:', e)
+      return false
+    }
+
+    if (!shiki) {
+      return false
+    }
+
+    // Already loaded
+    if (shiki.getLoadedLanguages().includes(lang)) {
+      return true
+    }
+
+    // Check if already loading
+    const existingPromise = languageLoadPromises.get(lang)
+    if (existingPromise) {
+      return existingPromise
+    }
+
+    // Start loading
+    const loadPromise = (async () => {
+      const importer = highlighterImports[lang as BundledLanguage]
+
+      if (!importer) {
+        console.warn(`Shiki language "${lang}" not available.`)
+        return false
+      }
+
+      try {
+        const mod = await importer()
+        await shiki!.loadLanguage(mod.default)
+        return true
+      } catch (e) {
+        console.error(`Failed to load Shiki language "${lang}":`, e)
+        return false
+      } finally {
+        languageLoadPromises.delete(lang)
+      }
+    })()
+
+    languageLoadPromises.set(lang, loadPromise)
+    return loadPromise
+  }
+
   function isReady(): boolean {
     return shiki !== null
   }
 
+  function isLanguageLoaded(lang: string): boolean {
+    return shiki?.getLoadedLanguages().includes(lang) ?? false
+  }
+
   function renderShiki(content: string, { lang, theme }: { lang: string, theme: string }) {
     if (shiki && shiki.getLoadedLanguages().includes(lang)) {
       return shiki.codeToHtml(content, {
@@ -72,6 +152,7 @@ export function useShiki() {
   function reset() {
     shiki = null
     initPromise = null
+    languageLoadPromises.clear()
     loading.value = true
   }
 
@@ -79,7 +160,9 @@ export function useShiki() {
     loading,
     renderShiki,
     init,
+    ensureLanguage,
     isReady,
+    isLanguageLoaded,
     reset,
     initShiki: async () => {
       console.warn('initShiki is deprecated, use init instead')

package/src/composables/useTheme.ts

@@ -92,6 +92,8 @@ export interface ResponseConfig {
   }
 }
 
+export type PlaygroundExampleBehavior = 'placeholder' | 'value' | 'ignore'
+
 export interface PlaygroundConfig {
   jsonEditor?: {
     mode?: Ref<PlaygroundJsonEditorMode>
@@ -99,6 +101,11 @@ export interface PlaygroundConfig {
     navigationBar?: Ref<boolean>
     statusBar?: Ref<boolean>
   }
+
+  examples?: {
+    behavior?: Ref<PlaygroundExampleBehavior>
+    playgroundExampleBehavior?: Ref<PlaygroundExampleBehavior>
+  }
 }
 
 export interface SecurityConfig {
@@ -175,7 +182,6 @@ export interface UseThemeConfig {
 }
 
 export interface CodeSamplesConfig {
-  langs: string[]
   defaultLang: string
   availableLanguages: LanguageConfig[]
   generator: GeneratorFunction
@@ -187,16 +193,24 @@ export interface LinksPrefixesConfig {
   operations: string
 }
 
-interface LanguageConfig {
+export interface LanguageConfig {
+  /** Unique identifier and Shiki highlighter language (e.g., 'curl', 'javascript', 'php') */
   lang: string
+  /** Display name shown in the UI */
   label: string
-  highlighter: string
+  /** Target language for @scalar/snippetz code generation (e.g., 'js', 'shell', 'python') */
+  target?: string
+  /** HTTP client for the target language (e.g., 'fetch', 'axios', 'curl') */
+  client?: string
+  /** Icon identifier for vitepress-plugin-group-icons */
   icon?: string
+  /** Shiki language for syntax highlighting (defaults to 'plain') */
+  highlighter?: string
 }
 
 export type PartialUseThemeConfig = Partial<UnwrapNestedRefs<UseThemeConfig>>
 
-type GeneratorFunction = (lang: string, request: OARequest) => Promise<string>
+type GeneratorFunction = (langConfig: LanguageConfig, request: OARequest) => Promise<string>
 
 type GetServersFunction = ({ method, path, operation }: { method: string, path: string, operation: ParsedOperation }) => string[] | null
 
@@ -220,24 +234,32 @@ export const availableLanguages: LanguageConfig[] = [
   {
     lang: 'curl',
     label: 'cURL',
+    target: 'shell',
+    client: 'curl',
     highlighter: 'bash',
     icon: 'curl',
   },
   {
     lang: 'javascript',
     label: 'JavaScript',
+    target: 'js',
+    client: 'fetch',
     highlighter: 'javascript',
     icon: '.js',
   },
   {
     lang: 'php',
     label: 'PHP',
+    target: 'php',
+    client: 'curl',
     highlighter: 'php',
     icon: '.php',
   },
   {
     lang: 'python',
     label: 'Python',
+    target: 'python',
+    client: 'requests',
     highlighter: 'python',
     icon: '.py',
   },
@@ -287,6 +309,10 @@ const defaultValues = {
       navigationBar: false,
       statusBar: false,
     },
+    examples: {
+      behavior: 'value' as PlaygroundExampleBehavior,
+      playgroundExampleBehavior: 'value' as PlaygroundExampleBehavior,
+    },
   },
   security: {
     defaultScheme: null as string | null,
@@ -338,15 +364,9 @@ const defaultValues = {
     disableDownload: false,
   },
   codeSamples: {
-    langs: [
-      'curl',
-      'javascript',
-      'php',
-      'python',
-    ],
     defaultLang: 'curl',
     availableLanguages,
-    generator: (lang: string, request: OARequest) => generateCodeSample(lang, request),
+    generator: (langConfig: LanguageConfig, request: OARequest) => generateCodeSample(langConfig, request),
     defaultHeaders: {},
   },
   linksPrefixes: {
@@ -403,6 +423,10 @@ const themeConfig: UseThemeConfig = {
       navigationBar: ref(defaultValues.playground.jsonEditor.navigationBar),
       statusBar: ref(defaultValues.playground.jsonEditor.statusBar),
     },
+    examples: {
+      behavior: ref(defaultValues.playground.examples?.behavior ?? 'value'),
+      playgroundExampleBehavior: ref(defaultValues.playground.examples?.playgroundExampleBehavior ?? 'value'),
+    },
   },
   security: {
     defaultScheme: ref(defaultValues.security.defaultScheme),
@@ -433,7 +457,6 @@ const themeConfig: UseThemeConfig = {
     disableDownload: ref(defaultValues.spec.disableDownload),
   },
   codeSamples: {
-    langs: defaultValues.codeSamples.langs,
     defaultLang: defaultValues.codeSamples.defaultLang,
     availableLanguages: defaultValues.codeSamples.availableLanguages,
     generator: defaultValues.codeSamples.generator,
@@ -525,6 +548,12 @@ export function useTheme(initialConfig: PartialUseThemeConfig = {}) {
     if (config.playground?.jsonEditor?.statusBar !== undefined) {
       ensureNestedRefProperty(themeConfig, ['playground', 'jsonEditor'], 'statusBar', config.playground.jsonEditor.statusBar)
     }
+    if (config.playground?.examples?.behavior !== undefined) {
+      ensureNestedRefProperty(themeConfig, ['playground', 'examples'], 'behavior', config.playground.examples.behavior)
+    }
+    if (config.playground?.examples?.playgroundExampleBehavior !== undefined) {
+      ensureNestedRefProperty(themeConfig, ['playground', 'examples'], 'playgroundExampleBehavior', config.playground.examples.playgroundExampleBehavior)
+    }
 
     // Security
     if (config.security?.defaultScheme !== undefined) {
@@ -745,6 +774,22 @@ export function useTheme(initialConfig: PartialUseThemeConfig = {}) {
     ensureNestedRefProperty(themeConfig, ['playground', 'jsonEditor'], 'statusBar', value)
   }
 
+  function getPlaygroundExamplesBehavior(): PlaygroundExampleBehavior {
+    return themeConfig?.playground?.examples?.behavior?.value ?? 'value'
+  }
+
+  function setPlaygroundExamplesBehavior(value: PlaygroundExampleBehavior) {
+    ensureNestedRefProperty(themeConfig, ['playground', 'examples'], 'behavior', value)
+  }
+
+  function getPlaygroundXExampleBehavior(): PlaygroundExampleBehavior {
+    return themeConfig?.playground?.examples?.playgroundExampleBehavior?.value ?? 'value'
+  }
+
+  function setPlaygroundXExampleBehavior(value: PlaygroundExampleBehavior) {
+    ensureNestedRefProperty(themeConfig, ['playground', 'examples'], 'playgroundExampleBehavior', value)
+  }
+
   function getSecurityDefaultScheme(): string | null | undefined {
     return themeConfig?.security?.defaultScheme?.value
   }
@@ -884,19 +929,10 @@ export function useTheme(initialConfig: PartialUseThemeConfig = {}) {
     }
   }
 
-  function getCodeSamplesLangs() {
-    const codeSamples = ensureNestedProperty(themeConfig, 'codeSamples')
-
-    if (!codeSamples.langs) {
-      codeSamples.langs = defaultValues.codeSamples.langs
-    }
-
-    return codeSamples.langs.filter((lang, index, self) => self.indexOf(lang) === index)
-  }
-
   function getCodeSamplesDefaultLang() {
-    const availableLangs = getCodeSamplesLangs() || []
+    const availableLanguages = getCodeSamplesAvailableLanguages()
     const codeSamples = ensureNestedProperty(themeConfig, 'codeSamples')
+    const availableLangs = availableLanguages.map(l => l.lang)
 
     if (codeSamples.defaultLang && availableLangs.includes(codeSamples.defaultLang)) {
       return codeSamples.defaultLang
@@ -905,10 +941,12 @@ export function useTheme(initialConfig: PartialUseThemeConfig = {}) {
     return availableLangs[0]
   }
 
-  function getCodeSamplesAvailableLanguages() {
+  function getCodeSamplesAvailableLanguages(filter: Array<string> = []) {
     const codeSamples = ensureNestedProperty(themeConfig, 'codeSamples')
-
-    return codeSamples.availableLanguages
+    if (filter.length) {
+      return codeSamples.availableLanguages?.filter(lang => filter.includes(lang.lang)) || []
+    }
+    return codeSamples.availableLanguages || []
   }
 
   function getCodeSamplesGenerator() {
@@ -930,10 +968,6 @@ export function useTheme(initialConfig: PartialUseThemeConfig = {}) {
   function setCodeSamplesConfig(config: Partial<UnwrapNestedRefs<CodeSamplesConfig>>) {
     const codeSamples = ensureNestedProperty(themeConfig, 'codeSamples')
 
-    if (config.langs) {
-      codeSamples.langs = config.langs.filter((lang, index, self) => self.indexOf(lang) === index)
-    }
-
     if (config.defaultLang) {
       codeSamples.defaultLang = config.defaultLang
     }
@@ -953,20 +987,7 @@ export function useTheme(initialConfig: PartialUseThemeConfig = {}) {
 
   function setCodeSamplesAvailableLanguages(languages: LanguageConfig[]) {
     const codeSamples = ensureNestedProperty(themeConfig, 'codeSamples')
-
-    if (!codeSamples.availableLanguages) {
-      codeSamples.availableLanguages = defaultValues.codeSamples.availableLanguages
-    }
-
-    const uniqueLanguages = [...new Set(languages.map(({ lang }) => lang))]
-
-    codeSamples.availableLanguages = uniqueLanguages.map((lang) => {
-      const language
-        = languages.find(l => l.lang === lang)
-          ?? availableLanguages.find(l => l.lang === lang)
-
-      return language || { lang, label: lang, highlighter: 'plaintext' }
-    })
+    codeSamples.availableLanguages = languages
   }
 
   function getLinksPrefixesConfig() {
@@ -1091,6 +1112,10 @@ export function useTheme(initialConfig: PartialUseThemeConfig = {}) {
     setPlaygroundJsonEditorNavigationBar,
     getPlaygroundJsonEditorStatusBar,
     setPlaygroundJsonEditorStatusBar,
+    getPlaygroundExamplesBehavior,
+    setPlaygroundExamplesBehavior,
+    getPlaygroundXExampleBehavior,
+    setPlaygroundXExampleBehavior,
     getSecurityDefaultScheme,
     setSecurityDefaultScheme,
     getOperationBadges,
@@ -1109,7 +1134,6 @@ export function useTheme(initialConfig: PartialUseThemeConfig = {}) {
     getWrapExamples,
     getSpecDisableDownload,
     setSpecConfig,
-    getCodeSamplesLangs,
     getCodeSamplesDefaultLang,
     getCodeSamplesAvailableLanguages,
     getCodeSamplesGenerator,

package/src/lib/codeSamples/generateCodeSample.ts

@@ -1,32 +1,33 @@
-import type { ClientId, TargetId } from '@scalar/types/snippetz'
+import type { LanguageConfig } from '../../composables/useTheme'
 import { snippetz } from '@scalar/snippetz'
 import { buildHarRequest } from './buildHarRequest'
 import { buildRequest } from './buildRequest'
 import { OARequest } from './request'
 
-const languagesMap: Record<string, TargetId> = {
-  curl: 'shell',
-  javascript: 'js',
-  php: 'php',
-  python: 'python',
-}
-
-const clientsMap: Record<string, ClientId<TargetId>> = {
-  curl: 'curl',
-  javascript: 'fetch',
-  php: 'curl',
-  python: 'requests',
-}
-
-export async function generateCodeSample(lang: string, request: OARequest | any): Promise<string> {
+export async function generateCodeSample(
+  langConfig: LanguageConfig,
+  request: OARequest | any,
+): Promise<string> {
   const oaRequest = request instanceof OARequest
     ? request
     : buildRequest(request)
 
   const harRequest = buildHarRequest(oaRequest)
 
+  const { lang, target, client } = langConfig
+
+  if (!target) {
+    console.error(`Language "${lang}" has missing property "target" in availableLanguages`)
+    return ''
+  }
+
+  if (!client) {
+    console.error(`Language "${lang}" has missing property "client" in availableLanguages`)
+    return ''
+  }
+
   try {
-    return snippetz().print(languagesMap[lang], clientsMap[lang], harRequest) ?? ''
+    return snippetz().print(target as any, client as any, harRequest) ?? ''
   } catch (e) {
     console.error(e, request)
     return ''

package/src/lib/examples/getPropertyExample.ts

@@ -63,7 +63,7 @@ function firstFromExamples(
   }
 }
 
-export function getPropertyExample(property: any): any {
+export function getPlaygroundSpecificExample(property: any): any {
   if (property?.['x-playground-example'] !== undefined) {
     return property['x-playground-example']
   }
@@ -72,6 +72,10 @@ export function getPropertyExample(property: any): any {
     return property.schema['x-playground-example']
   }
 
+  return null
+}
+
+export function getStandardExample(property: any): any {
   if (property?.example !== undefined) {
     return property.example
   }
@@ -104,3 +108,7 @@ export function getPropertyExample(property: any): any {
 
   return null
 }
+
+export function getPropertyExample(property: any): any {
+  return getPlaygroundSpecificExample(property) ?? getStandardExample(property)
+}

package/src/lib/parser/generateCodeSamples.ts

@@ -56,7 +56,7 @@ export async function generateCodeSamples(spec: ParsedOpenAPI): Promise<ParsedOp
         availableLanguages.map(async (language) => {
           return {
             ...language,
-            source: await generateCodeSample(language.lang, request),
+            source: await generateCodeSample(language, request),
           }
         }),
       )