vitepress-openapi 0.1.14 → 0.1.16

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 {
@@ -144,6 +151,10 @@ export interface ServerConfig {
   getServers?: GetServersFunction | null
 }
 
+export interface StorageConfig {
+  prefix?: string
+}
+
 export interface OperationLinkConfig {
   linkPrefix?: string
   transformHref?: (href: string) => string
@@ -171,6 +182,7 @@ export interface UseThemeConfig {
   codeSamples?: Partial<CodeSamplesConfig>
   linksPrefixes?: Partial<LinksPrefixesConfig>
   server?: Partial<ServerConfig>
+  storage?: Partial<StorageConfig>
   markdown?: Partial<MarkdownConfig>
 }
 
@@ -222,6 +234,7 @@ export const DEFAULT_OPERATION_SLOTS: OperationSlot[] = [
 ]
 
 export const DEFAULT_BASE_URL = 'http://localhost'
+export const DEFAULT_STORAGE_PREFIX = '--oa'
 
 export const availableLanguages: LanguageConfig[] = [
   {
@@ -302,6 +315,10 @@ const defaultValues = {
       navigationBar: false,
       statusBar: false,
     },
+    examples: {
+      behavior: 'value' as PlaygroundExampleBehavior,
+      playgroundExampleBehavior: 'value' as PlaygroundExampleBehavior,
+    },
   },
   security: {
     defaultScheme: null as string | null,
@@ -366,6 +383,9 @@ const defaultValues = {
     allowCustomServer: false,
     getServers: null,
   },
+  storage: {
+    prefix: DEFAULT_STORAGE_PREFIX,
+  },
   markdown: {
     operationLink: {
       linkPrefix: DEFAULT_OPERATIONS_PREFIX,
@@ -412,6 +432,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),
@@ -455,6 +479,9 @@ const themeConfig: UseThemeConfig = {
     allowCustomServer: defaultValues.server.allowCustomServer,
     getServers: defaultValues.server.getServers,
   },
+  storage: {
+    prefix: defaultValues.storage.prefix,
+  },
   markdown: {
     operationLink: {
       linkPrefix: defaultValues.markdown.operationLink.linkPrefix,
@@ -533,6 +560,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) {
@@ -584,6 +617,11 @@ export function useTheme(initialConfig: PartialUseThemeConfig = {}) {
       setServerConfig(config.server)
     }
 
+    // Storage
+    if (config.storage !== undefined) {
+      setStorageConfig(config.storage)
+    }
+
     // Markdown
     if (config.markdown !== undefined) {
       setMarkdownConfig(config.markdown)
@@ -753,6 +791,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
   }
@@ -1036,6 +1090,17 @@ export function useTheme(initialConfig: PartialUseThemeConfig = {}) {
     return themeConfig.markdown?.operationLink
   }
 
+  function getStoragePrefix(): string {
+    return themeConfig?.storage?.prefix ?? DEFAULT_STORAGE_PREFIX
+  }
+
+  function setStorageConfig(config: Partial<StorageConfig>) {
+    const storage = ensureNestedProperty(themeConfig, 'storage')
+    if (config.prefix !== undefined) {
+      storage.prefix = config.prefix
+    }
+  }
+
   return {
     isDark,
     schemaConfig: themeConfig.requestBody,
@@ -1075,6 +1140,10 @@ export function useTheme(initialConfig: PartialUseThemeConfig = {}) {
     setPlaygroundJsonEditorNavigationBar,
     getPlaygroundJsonEditorStatusBar,
     setPlaygroundJsonEditorStatusBar,
+    getPlaygroundExamplesBehavior,
+    setPlaygroundExamplesBehavior,
+    getPlaygroundXExampleBehavior,
+    setPlaygroundXExampleBehavior,
     getSecurityDefaultScheme,
     setSecurityDefaultScheme,
     getOperationBadges,
@@ -1109,5 +1178,7 @@ export function useTheme(initialConfig: PartialUseThemeConfig = {}) {
     getExternalLinksNewTab,
     setMarkdownConfig,
     getOperationLinkConfig,
+    getStoragePrefix,
+    setStorageConfig,
   }
 }

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/operation/operationData.ts

@@ -36,7 +36,9 @@ export function initOperationData({
 }): OperationData {
   const firstSecurityScheme = operation.securityUi?.[0]?.id || ''
 
-  const defaultSecurityScheme = useTheme().getSecurityDefaultScheme() || firstSecurityScheme
+  const theme = useTheme()
+  const defaultSecurityScheme = theme.getSecurityDefaultScheme() || firstSecurityScheme
+  const storagePrefix = theme.getStoragePrefix()
 
   return {
     operationId: operation.operationId,
@@ -46,7 +48,7 @@ export function initOperationData({
     playground: {
       request: ref(request || {} as OARequest),
       selectedServer: isLocalStorageAvailable()
-        ? useStorage(`--oa-operation-${operation.operationId}-selectedServer`, selectedServer, localStorage, {
+        ? useStorage(`${storagePrefix}-operation-${operation.operationId}-selectedServer`, selectedServer, localStorage, {
             mergeDefaults: true,
           })
         : ref(selectedServer),

package/src/lib/parser/getSchemaUi.ts

@@ -234,6 +234,7 @@ class UiPropertyFactory {
               schema.items.properties,
               schema.items.required || [],
               schema.items.additionalProperties,
+              schema.items['x-additionalPropertiesName'],
             )
           : undefined
 
@@ -334,6 +335,7 @@ class UiPropertyFactory {
         schema.properties,
         schema.required || [],
         schema.additionalProperties,
+        schema['x-additionalPropertiesName'],
       )
     } else if (schema.type === undefined) {
       if (schema.properties || schema.additionalProperties) {
@@ -342,6 +344,7 @@ class UiPropertyFactory {
           schema.properties,
           schema.required || [],
           schema.additionalProperties,
+          schema['x-additionalPropertiesName'],
         )
       }
     }
@@ -353,6 +356,7 @@ class UiPropertyFactory {
     propertiesNode?: Record<string, OpenAPI.SchemaObject>,
     requiredProperties: string[] = [],
     additionalPropertiesNode?: OpenAPI.SchemaObject | boolean,
+    additionalPropertiesName?: string,
   ): OAProperty[] {
     const properties: OAProperty[] = []
 
@@ -368,12 +372,11 @@ class UiPropertyFactory {
         ? additionalPropertiesNode
         : { type: 'string' }
 
-      properties.push({
-        name: 'additionalProperties',
-        types: [additionalProps.type as JSONSchemaType],
-        required: false,
-        meta: { isAdditionalProperties: true },
-      })
+      const name = additionalPropertiesName || 'additionalProperties'
+      const property = UiPropertyFactory.schemaToUiProperty(name, additionalProps)
+      property.required = false
+      property.meta = { ...(property.meta || {}), isAdditionalProperties: true }
+      properties.push(property)
     }
 
     return properties

package/src/lib/playground/playgroundExampleBehavior.ts

@@ -0,0 +1,48 @@
+import type { PlaygroundExampleBehavior } from '../../composables/useTheme'
+import { getPlaygroundSpecificExample, getStandardExample } from '../examples/getPropertyExample'
+
+export function useExampleForPlaceholder(behavior: PlaygroundExampleBehavior): boolean {
+  return behavior !== 'ignore'
+}
+
+export function useExampleForValue(behavior: PlaygroundExampleBehavior): boolean {
+  return behavior === 'value'
+}
+
+export function resolveExampleForValue(
+  property: any,
+  behavior: PlaygroundExampleBehavior,
+  xExampleBehavior: PlaygroundExampleBehavior = 'value',
+): any {
+  if (useExampleForValue(xExampleBehavior)) {
+    const specific = getPlaygroundSpecificExample(property)
+    if (specific !== null) {
+      return specific
+    }
+  }
+
+  if (useExampleForValue(behavior)) {
+    return getStandardExample(property)
+  }
+
+  return null
+}
+
+export function resolveExampleForPlaceholder(
+  property: any,
+  behavior: PlaygroundExampleBehavior,
+  xExampleBehavior: PlaygroundExampleBehavior = 'value',
+): any {
+  if (useExampleForPlaceholder(xExampleBehavior)) {
+    const specific = getPlaygroundSpecificExample(property)
+    if (specific !== null) {
+      return specific
+    }
+  }
+
+  if (useExampleForPlaceholder(behavior)) {
+    return getStandardExample(property)
+  }
+
+  return null
+}