### Example Markdown for Custom Server

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/custom-server.md

This markdown file demonstrates the setup for enabling a custom server in the Playground.

```markdown
---
aside: false
outline: false
title: vitepress-openapi
---

<!--@include: ./parts/custom-server-example.md-->
```

--------------------------------

### Install vitepress-openapi with bun

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/guide/getting-started.md

Install the vitepress-openapi package using bun.

```sh
bun add vitepress-openapi
```

--------------------------------

### Define Playground-Specific Parameter Example

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/playground-examples.md

Use the `x-playground-example` extension in your OpenAPI JSON to provide examples specifically for the playground, overriding the general `example`.

```json
{
  "name": "id",
  "in": "query",
  "required": false,
  "description": "Filter by ID",
  "x-playground-example": "playground-specific-value",
  "schema": {
    "type": "string",
    "example": "general-example-value"
  }
}
```

--------------------------------

### Configure Playground Examples Behavior

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/composables/useTheme.md

Sets the behavior for applying example values from OpenAPI specs in the playground. Use 'placeholder' to show as placeholder text, 'value' to pre-fill, or 'ignore' to not use the example.

```typescript
useTheme({
  playground: {
    examples: {
      behavior: 'placeholder',           // for spec `example` fields
      playgroundExampleBehavior: 'value', // for spec `x-playground-example` fields
    },
  },
})
```

--------------------------------

### Install vitepress-openapi with yarn

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/guide/getting-started.md

Install the vitepress-openapi package using yarn.

```sh
yarn add vitepress-openapi
```

--------------------------------

### Install vitepress-openapi with npm

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/guide/getting-started.md

Install the vitepress-openapi package using npm.

```sh
npm install vitepress-openapi
```

--------------------------------

### Install vitepress-openapi with pnpm

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/guide/getting-started.md

Install the vitepress-openapi package using pnpm.

```sh
pnpm add vitepress-openapi
```

--------------------------------

### Define Playground-Specific Schema Example

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/playground-examples.md

The `x-playground-example` extension can also be applied at the schema level to provide playground-specific examples.

```json
{
  "name": "id",
  "in": "query",
  "required": false,
  "description": "Filter by ID",
  "schema": {
    "type": "string",
    "example": "general-example-value",
    "x-playground-example": "schema-level-playground-example"
  }
}
```

--------------------------------

### Vue Component Setup with vitepress-openapi

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/e2e/local/dev/docs/tests/[testSlug].md

This script setup configures the vitepress-openapi plugin by importing necessary functions and hooks. It retrieves route parameters for test slugs, spec URLs, and theme configurations, and sets up theme initialization and reset logic using `onBeforeMount` and `onBeforeUnmount` lifecycle hooks.

```vue
import { onBeforeMount, onBeforeUnmount } from 'vue'
import { useRoute } from 'vitepress'
import { useTheme } from 'vitepress-openapi/client'

const route = useRoute()

const testSlug = route.data.params.testSlug
const specUrl = route.data.params.specUrl
const themeConfig = route.data.params.themeConfig

onBeforeMount(() => {
    useTheme(themeConfig)
})

onBeforeUnmount(() => {
    useTheme().reset()
})
```

--------------------------------

### Markdown Configuration Example

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/operation-badges.md

Example of a Markdown file configuration for vitepress-openapi, likely used in conjunction with operation badges.

```markdown
---
aside: false
outline: false
title: vitepress-openapi
---

<!--@include: ./parts/operation-badges-example.md-->
```

--------------------------------

### VitePress Configuration for Custom Slots Example

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/custom-slots.md

This markdown frontmatter configures VitePress for the custom slots example, disabling the aside and outline for a cleaner display. It includes the custom slots example from a separate file.

```markdown
---
aside: false
outline: false
title: vitepress-openapi
---

<!--@include: ./parts/custom-slots-example.md-->
```

--------------------------------

### Configure Playground Example Behavior

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/playground-examples.md

Control how standard and playground-specific examples are used in the playground by setting `behavior` and `playgroundExampleBehavior` within `useTheme`.

```typescript
useTheme({
  playground: {
    examples: {
      behavior: 'placeholder',
      playgroundExampleBehavior: 'value',
    },
  },
})
```

--------------------------------

### Vue.js Component Setup with vitepress-openapi

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/tests/[testSlug].md

This script setup configures the necessary Vue.js and VitePress hooks to initialize and manage the theme for vitepress-openapi. It imports essential modules like `onUnmounted`, `useRoute`, and `useTheme`. Ensure that `route.data.params` contains `testSlug`, `spec`, and `themeConfig` for proper initialization.

```vue
import { onUnmounted } from 'vue'
import { useRoute } from 'vitepress'
import { useTheme } from 'vitepress-openapi/client'

const route = useRoute()

const testSlug = route.data.params.testSlug
const spec = JSON.parse(JSON.stringify(route.data.params.spec))
const themeConfig = route.data.params.themeConfig

useTheme(themeConfig)

onUnmounted(() => {
    useTheme().reset()
})
```

--------------------------------

### Generate Sidebar Links

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/sidebar-examples/index.md

Generates an unordered list of HTML links for sidebar navigation based on provided example configurations. Ensure the 'examples' import is available.

```javascript
import { examples } from '../sidebar-examples-configs.ts'

const list = examples.map(example => {
return `<ul><li><a href="/sidebar-examples/${example.slug}">${example.label}</a></li></ul>`
}).join('
')
```

--------------------------------

### Import and Use useOpenapi Hook

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/example/introduction.md

Import the useOpenapi hook from 'vitepress-openapi/client' to access OpenAPI data. This example shows how to retrieve all paths grouped by HTTP verbs.

```javascript
import { useOpenapi } from 'vitepress-openapi/client'

const paths = useOpenapi().getPathsByVerbs()
```

--------------------------------

### Configure Server Options

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/composables/useTheme.md

Customize server behavior in VitePress OpenAPI, including setting a custom function to get servers and allowing custom server URLs.

```javascript
server: {
    getServers: ({ method, path, operation }) => Array<string>,
    allowCustomServer: true,
}
```

--------------------------------

### Use VitePress Theme Utility Functions

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/composables/useTheme.md

Access and utilize utility functions from the useTheme composable, such as checking dark mode, resetting configuration, and getting the current state.

```javascript
const { isDark, reset, getState } = useTheme()

// Reactively read dark mode
console.log(isDark.value) // true | false

// Reset all config to defaults
reset()

// Read full config as a plain object
console.log(getState())
```

--------------------------------

### Configure VitePress OpenAPI Theme

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/composables/useTheme.md

Use the `useTheme` composable in your `.vitepress/theme/index.js` file to set theme configurations. This example shows how to configure highlighter themes, path display, default views, JSON/schema viewers, heading levels, response settings, playground options, operation slots, and i18n messages.

```typescript
import { useTheme, locales } from 'vitepress-openapi/client'

export default {
    async enhanceApp({app, router, siteData}) {
        useTheme({
            theme: {
                highlighterTheme: {
                    light: 'vitesse-light',
                    dark: 'vitesse-dark',
                },
            },
            path: {
                // Show the base URL in the path component.
                showBaseURL: false,
            },
            requestBody: {
                // Set the default schema view.
                defaultView: 'schema', // schema or contentType
            },
            jsonViewer: {
                // How many levels are expanded on load.
                deep: Infinity,
                // Set the JSON viewer renderer.
                renderer: 'vue-json-pretty', // vue-json-pretty or shiki
            },
            schemaViewer: {
                // How many levels are expanded on load.
                deep: 1,
            },
            // Set the heading levels.
            headingLevels: {
                h1: 1,
                h2: 2,
                h3: 3,
                h4: 4,
                h5: 5,
                h6: 6,
            },
            response: {
                // Set the response code selector.
                responseCodeSelector: 'tabs', // tabs or select
                // Set the maximum number of tabs, after which a Select will be shown.
                maxTabs: 5,
                body: {
                    // Set the default view.
                    defaultView: 'schema', // schema or contentType
                },
            },
            playground: {
                jsonEditor: {
                    // Set the mode of the JSON editor.
                    mode: 'tree', // text, tree, or table
                    // Set the visibility of the main menu bar.
                    mainMenuBar: false,
                    // Set the visibility of the navigation bar.
                    navigationBar: false,
                    // Set the visibility of the status bar.
                    statusBar: false,
                },
                examples: {
                    // Behavior for standard `example` / `examples` fields.
                    behavior: 'value', // placeholder, value, or ignore
                    // Behavior for `x-playground-example` extension field.
                    playgroundExampleBehavior: 'value', // placeholder, value, or ignore
                },
            },
            operation: {
                // Set the operation badges. The order is respected.
                badges: ['deprecated'],
                // Slots to render in the OAOperation component.
                slots: [
                    'header',
                    'path',
                    'description',
                    'security',
                    'parameters',
                    'request-body',
                    'responses',
                    'playground',
                    'code-samples',
                    'branding',
                    'footer',
                ],
                // Slots to hide in the OAOperation component.
                hiddenSlots: [],
                // Set the number of columns to use in the OAOperation component.
                cols: 2,
                // Set the default base URL.
                defaultBaseUrl: 'http://localhost',
                // Deprecated. Use `server.getServers` instead.
                getServers: ({ method, path, operation }) => Array<string>,
            },
            // Set the i18n configuration.
            i18n: {
                locale: 'en', // en | es | ja | pt-BR | string
                fallbackLocale: 'en', // en | es | ja | pt-BR | string
                messages: {
                    en: {
                        ...locales.en,
                        'operation.badgePrefix.operationId': 'Operation ID',
                    },
                    es: {
                        ...locales.es,
                        'operation.badgePrefix.operationId': 'ID de operación',
                    },
                },
                availableLocales: [
                    { code: 'en', label: 'English' },
                    { code: 'es', label: 'Español' },
                    { code: 'ja', label: 'Japanese' },
                    { code: 'pt-BR', label: 'Português (Brasil)' },
                    { code: 'zh', label: '中文' },
                ],
            },
            // Set spec configuration.
            spec: {
                groupByTags: true, // Group paths by tags.
                collapsePaths: false, // Collapse paths when grouping by tags.
            },
        })
    }
}
```

--------------------------------

### Vue Component Setup with vitepress-openapi

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/examples/[exampleSlug].md

This script sets up the necessary lifecycle hooks and imports for using the vitepress-openapi component. It configures the theme and retrieves route parameters for the OpenAPI specification URL.

```vue
import { onBeforeMount, onBeforeUnmount } from 'vue'
import { useRoute } from 'vitepress'
import { useTheme } from 'vitepress-openapi/client'

const route = useRoute()

const exampleSlug = route.data.params.exampleSlug
const specUrl = route.data.params.specUrl
const themeConfig = route.data.params.themeConfig

onBeforeMount(() => {
    useTheme(themeConfig)
})

onBeforeUnmount(() => {
    useTheme().reset()
})
```

--------------------------------

### GET /artists

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/parts/hide-branding-prop-example.md

Retrieves a list of all artists.

```APIDOC
## GET /artists

### Description
Retrieves a list of all artists.

### Method
GET

### Endpoint
/artists

### Parameters

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **artists** (array) - A list of artist objects.

#### Response Example
{
  "artists": [
    {
      "id": "string",
      "name": "string"
    }
  ]
}
```

--------------------------------

### Configure Custom Code Sample Generator

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/parts/code-samples-example.md

Use `useTheme` in `onBeforeMount` to add a custom language for code samples. This example adds 'bruno' as a language, providing a custom generator function.

```typescript
import {
    onBeforeMount,
    onBeforeUnmount
} from 'vue'
import {
    useTheme,
    generateCodeSample
} from 'vitepress-openapi/client'

onBeforeMount(() => {
    useTheme({
        codeSamples: {
            availableLanguages: [
                {
                    lang: 'bruno',
                    label: 'Bruno',
                    highlighter: 'plaintext',
                },
                ...useTheme().getCodeSamplesAvailableLanguages(),
            ],
            defaultLang: 'bruno',
            generator: async (langConfig, request) => {
                if (langConfig.lang === 'bruno') {
                    return generateBruRequest(request)
                }

                return generateCodeSample(langConfig, request)
            },
        },
    })
})

onBeforeUnmount(() => {
    useTheme().reset()
})
```

--------------------------------

### Generate Sidebar Items by Paths with VitePress OpenAPI

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/sidebar/sidebar-items.md

Configure your `.vitepress/config.js` to use `useSidebar` and `itemsByPaths` for dynamic sidebar generation. This example shows optional configurations like filtering paths, setting collapsible items, defining depth, and specifying link prefixes.

```javascript
import { useSidebar } from 'vitepress-openapi'
import spec from '../public/openapi.json' with { type: 'json' }

const sidebar = useSidebar({ spec })

module.exports = {
    // ...
    themeConfig: {
        sidebar: [
            ...sidebar.itemsByPaths({
                /**
                 * Optionally, you can filter paths by a prefix. Default is an empty string.
                 */
                startsWith: '',

                /**
                 * Optionally, you can specify if the sidebar items are collapsible. Default is true.
                 */
                collapsible: true,

                /**
                 * Optionally, you can specify a depth for the sidebar items. Default is 6, which is the maximum VitePress sidebar depth.
                 */
                depth: 6,

                /**
                 * Optionally, you can specify a link prefix for all generated sidebar items. Default is `/operations/`.
                 */
                linkPrefix: '/operations/',

                /**
                 * Optionally, you can specify a template for the sidebar items. You can see the default value
                 * in `sidebarItemTemplate` function in the `useSidebar` composable.
                 */
                //sidebarItemTemplate: ({ method, path, title }): string => `[${method}] ${title || path}`,

                /**
                 * Optionally, you can specify a template for the sidebar groups.
                 */
                //sidebarGroupTemplate: ({ path, depth }): string => path,
            }),
        ],
    },
}
```

--------------------------------

### Custom Code Generator Example

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/code-samples.md

Implement a custom code generator for languages not supported by `@scalar/snippetz` by providing a `generator` function.

```typescript
useTheme({
  codeSamples: {
    availableLanguages: [
      ...useTheme().getCodeSamplesAvailableLanguages(),
      {
        lang: 'bru',
        label: 'Bru',
        icon: '.bru',
        generator: async (langConfig, request) => {
          // Custom logic to convert request to Bru code
          return generateCodeSample(langConfig, request);
        },
      },
    ],
  },
})
```

--------------------------------

### Include Operation Tags Slot

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/operation-tags-slot.md

Use `useTheme` with `operation.slots` including 'tags' to display operation tags. This example shows the configuration for the VitePress page.

```markdown
---
aside: false
outline: false
title: vitepress-openapi
---

<!--@include: ./parts/operation-tags-slot-example.md-->
```

--------------------------------

### Configure VitePress OpenAPI Theme

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/composables/useTheme.md

Set various theme options for VitePress OpenAPI, such as path summary display, circular reference handling, lazy rendering, default tags, example wrapping, and disabling the download button.

```javascript
useTheme({
    showPathsSummary: true,
    avoidCirculars: false,
    lazyRendering: false,
    defaultTag: 'Default',
    defaultTagDescription: '',
    wrapExamples: true,
    disableDownload: false,
})
```

--------------------------------

### Configure Operation Badges in VitePress OpenAPI

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/parts/operation-badges-example.md

Use the `useTheme` composable within `onBeforeMount` to set custom badges for API operations. This example configures 'deprecated' and 'operationId' badges.

```vue
<script setup lang="ts">
import { onBeforeMount, onBeforeUnmount } from 'vue'
import { useTheme } from 'vitepress-openapi/client'

onBeforeMount(() => {
    useTheme({
        operation: {
            badges: ['deprecated', 'operationId'],
        },
    })
})
</script>

<OASpec />
```

--------------------------------

### Render Operation with Global Spec

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/pages/by-operation.md

Markdown snippet to render an API operation using the OAOperation component. Assumes the OpenAPI specification is globally configured via `useOpenapi` in your theme setup.

```markdown
---
aside: false
outline: false
title: vitepress-openapi
---

<script setup lang="ts">
import { useRoute } from 'vitepress'

const route = useRoute()

const operationId = route.data.params.operationId
</script>

<OAOperation :operationId="operationId" />
```

--------------------------------

### Vue Component for Sidebar Example

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/sidebar-examples/[exampleSlug].md

This Vue component uses VitePress's useRoute hook to access route parameters and dynamically generate sidebar content. It imports necessary VitePress and vitepress-openapi modules, along with the OpenAPI spec.

```js-vue
import { defineConfig } from 'vitepress'
import { useSidebar } from 'vitepress-openapi'
import spec from '../docs/public/openapi.json'

{{code}}
```

--------------------------------

### Create VitePress Project with Starter Template

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/guide/getting-started.md

Use this command to quickly set up a new VitePress project with vitepress-openapi pre-configured.

```sh
npx degit enzonotario/vitepress-openapi-starter my-api-docs
```

--------------------------------

### Display OpenAPI Introduction Globally

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/pages/introduction.md

Use the OAIntroduction component directly in Markdown files if the OpenAPI spec is configured globally via useOpenapi.

```markdown
<OAIntroduction />
```

--------------------------------

### Enable Custom Server in Markdown

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/custom-server.md

In your `.md` files, import `useTheme` and set the `allowCustomServer` option to `true` to enable custom server URLs.

```markdown
<script setup>
import { useTheme } from 'vitepress-openapi/client'

useTheme({
    server: {
        allowCustomServer: true,
    },
})
</script>

<OASpec />
```

--------------------------------

### Display OpenAPI Introduction with Imported Spec

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/pages/introduction.md

Import the OpenAPI specification JSON and pass it as a 'spec' prop to OAIntroduction in Markdown files.

```typescript
import spec from '../public/openapi.json'

```

```markdown
<OAIntroduction :spec="spec" />
```

--------------------------------

### Configure vitepress-openapi Client

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/playground-examples.md

Import and use the `useOpenapi` hook to initialize the client with your OpenAPI specification file.

```javascript
import { useOpenapi } from 'vitepress-openapi/client'

useOpenapi({
  spec: '/openapi-playground-examples.json',
})
```

--------------------------------

### Display OpenAPI Info and Servers Globally

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/pages/introduction.md

Use OAInfo and OAServers components directly in Markdown files if the OpenAPI spec is configured globally via useOpenapi.

```markdown
<OAInfo />

<OAServers />
```

--------------------------------

### Customize OASpec Header with Slot Props

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/custom-slots.md

Apply scoped slot syntax to OASpec to customize the header for all operations. This example shows how to display the HTTP method and path for each operation.

```vue
<OASpec>
  <template #header="{ operation, method, path }">
    <h3>{{ method }} {{ path }}</h3>
  </template>
</OASpec>
```

--------------------------------

### Configure VitePress OpenAPI Theme

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/parts/custom-server-example.md

Use `useTheme` within `onBeforeMount` to configure the OpenAPI plugin's theme, allowing custom server configurations.

```javascript
import { onBeforeMount, onBeforeUnmount } from 'vue'
import { useTheme } from 'vitepress-openapi/client'

onBeforeMount(() => {
    useTheme({
        server: {
            allowCustomServer: true,
        },
    })
})

```

--------------------------------

### Enable Custom Server in Theme Index

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/custom-server.md

Configure the `useOpenapi` composable in your `.vitepress/theme/index.[js,ts]` file to allow custom server URLs by setting `allowCustomServer` to `true`.

```typescript
useOpenapi({
    spec,
    config: {
        server: {
            allowCustomServer: true,
        },
    },
})
```

--------------------------------

### Get Resolved Heading Level

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/composables/useTheme.md

Retrieves the mapped HTML tag string for a given heading level. Throws an error if the configured level is out of the valid range of 1 to 6.

```typescript
const { getHeadingLevel } = useTheme()
getHeadingLevel('h1') // → 'h1' (or whatever h1 is mapped to)
```

--------------------------------

### Display Specific Operation from Local JSON

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/guide/getting-started.md

Use the OAOperation component to display a specific operation from a local JSON OpenAPI specification. Requires importing the spec and getting the operationId from the route.

```vue
<script setup>
import { useRoute } from 'vitepress'
import spec from '../public/openapi.json'

const route = useRoute()

const operationId = route.data.params.operationId
</script>

<OAOperation :spec="spec" :operationId="operationId" />
```

--------------------------------

### Configure Playground with Custom Security Scheme Defaults

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/composables/usePlayground.md

Use the `usePlayground` composable in your `.vitepress/theme/index.js` to set custom default values for security schemes. This allows for pre-filling authentication details.

```typescript
import { usePlayground } from 'vitepress-openapi/client'

export default {
    async enhanceApp({ app, router, siteData }) {
        const playground = usePlayground()
        
        // Set custom security scheme default values.
        playground.setSecuritySchemeDefaultValues({
            'http-basic': 'Custom Basic Auth',
            'http-bearer': 'Custom Bearer Token',
            // ...
        })
    }
}
```

--------------------------------

### Render OpenAPI Spec Component

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/example/tags/[tag].md

Use the `<OASpec />` component to render your OpenAPI specification. Pass an array of tags to filter the displayed API endpoints. This example hides info, servers, and path summaries.

```vue
<OASpec :tags="[tag]" hide-info hide-servers hide-paths-summary />
```

--------------------------------

### Configure OpenAPI Globally (JavaScript)

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/guide/getting-started.md

Import and pass the OpenAPI JSON specification to the `useOpenapi` composable in your `.vitepress/theme/index.js` file. Ensure you import the correct `theme` and `useOpenapi` from `vitepress-openapi/client`.

```javascript
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import { theme, useOpenapi } from 'vitepress-openapi/client'
import 'vitepress-openapi/dist/style.css'

import spec from '../../public/openapi.json'

export default {
    extends: DefaultTheme,
    async enhanceApp({ app }) {
        // Set the OpenAPI specification.
        useOpenapi({
            spec,
        })

        // Use the theme.
        theme.enhanceApp({ app })
    }
}
```

--------------------------------

### Configure vitepress-openapi Theme in Markdown (OAOperation)

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/guide/getting-started.md

Configure the theme within a Markdown file for a specific operation using `useTheme`, the route, and the OpenAPI specification.

```md-vue
---
aside: false
outline: false
title: vitepress-openapi
---

<script setup>
import { useRoute } from 'vitepress'
import { useTheme } from 'vitepress-openapi/client' // [!code ++]
import spec from '../public/openapi.json'

const route = useRoute()

const operationId = route.data.params.operationId

useTheme({ // [!code ++]
{{''}}    // Custom theme configuration... [!code ++]
}) // [!code ++]
</script>

<OAOperation :spec="spec" :operationId="operationId" />
```

--------------------------------

### Configure vitepress-openapi Theme in Markdown (OASpec)

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/guide/getting-started.md

Configure the theme within a Markdown file using the `useTheme` composable and passing the OpenAPI specification.

```md-vue
---
aside: false
outline: false
title: vitepress-openapi
---

<script setup>
import { useTheme } from 'vitepress-openapi/client' // [!code ++]
import spec from '../public/openapi.json'

useTheme({ // [!code ++]
{{''}}    // Custom theme configuration... [!code ++]
}) // [!code ++]
</script>

<OASpec :spec="spec" />
```

--------------------------------

### Configure VitePress Theme with vitepress-openapi (JavaScript)

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/guide/getting-started.md

Integrate vitepress-openapi into your VitePress theme by importing the theme and CSS in your `.vitepress/theme/index.js` file.

```js
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import { theme } from 'vitepress-openapi/client' // [!code ++]
import 'vitepress-openapi/dist/style.css' // [!code ++]

export default {
    extends: DefaultTheme,
    async enhanceApp({ app }) {
        theme.enhanceApp({ app }) // [!code ++]
    }
}
```

--------------------------------

### Configure VitePress Theme with vitepress-openapi (TypeScript)

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/guide/getting-started.md

Integrate vitepress-openapi into your VitePress theme by importing the theme and CSS in your `.vitepress/theme/index.ts` file.

```ts
// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import type { Theme } from 'vitepress'
import { theme } from 'vitepress-openapi/client' // [!code ++]
import 'vitepress-openapi/dist/style.css' // [!code ++]

export default {
    extends: DefaultTheme,
    async enhanceApp({ app }) {
        theme.enhanceApp({ app }) // [!code ++]
    }
} satisfies Theme
```

--------------------------------

### Configure OpenAPI Globally (TypeScript)

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/guide/getting-started.md

Configure OpenAPI using TypeScript by importing and passing the JSON specification to `useOpenapi` in your `.vitepress/theme/index.ts`. Use the `with { type: 'json' }` syntax for importing JSON files.

```typescript
// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import type { Theme } from 'vitepress'
import { theme, useOpenapi } from 'vitepress-openapi/client'
import 'vitepress-openapi/dist/style.css'

import spec from '../../public/openapi.json' with { type: 'json' }

export default {
    extends: DefaultTheme,
    async enhanceApp({ app }) {
        // Set the OpenAPI specification.
        useOpenapi({
            spec,
        })

        // Use the theme.
        theme.enhanceApp({ app })
    }
} satisfies Theme
```

--------------------------------

### Import and Use minifyHtml Utility

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/utils/minifyHtml.md

Import `minifyHtml` from `vitepress-openapi` or `vitepress-openapi/client` to normalize HTML strings. This is useful for ensuring consistency between server and client rendering.

```typescript
import { minifyHtml } from 'vitepress-openapi'

const html = minifyHtml(`
  <span class="OASidebarItem">
    <span class="badge">GET</span>
    <span class="text">My Operation</span>
  </span>
`)

// Result: '<span class="OASidebarItem"> <span class="badge">GET</span> <span class="text">My Operation</span> </span>'
```

--------------------------------

### Configure Storage Options

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/composables/useTheme.md

Manage storage settings for VitePress OpenAPI, such as the localStorage key prefix and whether to persist authentication values.

```javascript
storage: {
    prefix: '--oa',
    persistAuth: true,
}
```

--------------------------------

### Display OpenAPI Info and Servers with Imported Spec

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/pages/introduction.md

Import the OpenAPI specification JSON and pass it as a 'spec' prop to OAInfo and OAServers components in Markdown files.

```typescript
import spec from '../public/openapi.json'

```

```markdown
<OAInfo :spec="spec" />

<OAServers :spec="spec" />
```

--------------------------------

### Configure vitepress-openapi Theme Globally (JavaScript)

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/guide/getting-started.md

Set the OpenAPI specification and custom theme configuration in your `.vitepress/theme/index.js` file using `useOpenapi`. Ensure the CSS is imported.

```js-vue
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import { theme, useOpenapi } from 'vitepress-openapi/client'
import 'vitepress-openapi/dist/style.css'

import spec from '../../public/openapi.json'

export default {
    extends: DefaultTheme,
    async enhanceApp({ app }) {
        // Set the OpenAPI specification.
        useOpenapi({
            spec,
            config: { // [!code ++]
            {{''}}    // Custom theme configuration... [!code ++]
            }, // [!code ++]
        })

        // Use the theme.
        theme.enhanceApp({ app })
    }
}
```

--------------------------------

### Import and Use useRoute in VitePress

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/example/operations/[operationId].md

Demonstrates importing and using the `useRoute` hook from `vitepress` to access route parameters. This is typically used to dynamically fetch and display data based on the current URL.

```typescript
import { useRoute } from 'vitepress'

const route = useRoute()

const operationId = route.data.params.operationId
```

--------------------------------

### Configure OpenAPI Globally with YAML (JavaScript)

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/guide/getting-started.md

Pass a YAML string directly to the `spec` prop of the `useOpenapi` composable in your `.vitepress/theme/index.js`. This allows for inline YAML OpenAPI definitions.

```javascript
// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import { theme, useOpenapi } from 'vitepress-openapi/client'
import 'vitepress-openapi/dist/style.css'

export default {
    extends: DefaultTheme,
    async enhanceApp({ app }) {
        // Set the OpenAPI specification.
        useOpenapi({
            spec: `
openapi: 3.0.4
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9

servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        "200": # status code
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
`,
        })

        // Use the theme.
        theme.enhanceApp({ app })
    }
}
```

--------------------------------

### Configure Shiki Highlighter Theme

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/composables/useTheme.md

Set custom themes for the Shiki syntax highlighter in both light and dark modes within VitePress.

```javascript
useTheme({
  theme: {
    highlighterTheme: {
      light: 'vitesse-light',
      dark: 'vitesse-dark',
    },
  },
})
```

--------------------------------

### Configure Code Samples

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/composables/useTheme.md

Sets the full configuration for code samples, including default language, available languages, a custom generator function, and default headers. The `availableLanguages` array defines how each language is presented in the UI and used for code generation.

```typescript
useTheme({
  codeSamples: {
    defaultLang: 'curl',
    availableLanguages: [
      {
        lang: 'curl',
        label: 'cURL',
        target: 'shell',
        client: 'curl',
        highlighter: 'bash',
        icon: 'curl',
      },
    ],
    generator: async (langConfig, request) => { /* return generated code string */ },
    defaultHeaders: { 'X-Custom': 'value' },
  },
})
```

--------------------------------

### Use Components with Global Configuration

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/components/index.md

If the OpenAPI specification is configured globally using `useOpenapi`, components like OASpec and OAOperation can be used without passing the spec or URL.

```vue
<OASpec />
<OAOperation operation-id="getUserById" />
```

--------------------------------

### Server Configuration API

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/composables/useTheme.md

API endpoints for managing the server configuration.

```APIDOC
## Server Configuration API

### Description
APIs for setting and getting the server configuration.

### Endpoints

#### `setServerConfig`

##### Description
Sets the server configuration, including how to get servers and whether custom servers are allowed.

##### Method
POST

##### Endpoint
`/server/config`

##### Request Body
- **getServers** (function) - Optional - A function that returns an array of server strings based on method, path, and operation.
- **allowCustomServer** (boolean) - Optional - Whether to allow custom server URLs.

### `getServerConfig`

##### Description
Gets the full server config object.

##### Method
GET

##### Endpoint
`/server/config`

### `getOperationServers`

##### Description
Gets the servers function for a specific operation.

##### Method
GET

##### Endpoint
`/server/config/operation-servers`

### `getServerAllowCustomServer`

##### Description
Gets whether custom servers are allowed.

##### Method
GET

##### Endpoint
`/server/config/allow-custom-server`
```

--------------------------------

### Configure vitepress-openapi Theme Globally (TypeScript)

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/guide/getting-started.md

Set the OpenAPI specification and custom theme configuration in your `.vitepress/theme/index.ts` file using `useOpenapi`. Ensure the CSS is imported.

```ts-vue
// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import type { Theme } from 'vitepress'
import { theme, useOpenapi } from 'vitepress-openapi
import 'vitepress-openapi/dist/style.css'

import spec from '../../public/openapi.json' with { type: 'json' }

export default {
    extends: DefaultTheme,
    async enhanceApp({ app }) {
        // Set the OpenAPI specification.
        useOpenapi({
            spec,
            config: { // [!code ++]
            {{''}}    // Custom theme configuration... [!code ++]
            }, // [!code ++]
        })

        // Use the theme.
        theme.enhanceApp({ app })
    }
} satisfies Theme
```

--------------------------------

### Customize Markdown-it Renderer

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/composables/useTheme.md

Use the `config` callback to add custom markdown-it plugins or provide a custom markdown-it instance. The `md` parameter is an instance of markdown-it.

```typescript
useTheme({
  markdown: {
    config: md => {
      // add custom markdown-it plugins
      md.use(myPlugin, myParams)
      return;

      // or return your own instance
      const myMd = (/* ... */)
      return myMd
    },
  },
})
```

--------------------------------

### Configure i18n with Custom Messages

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/i18n.md

Use the `useTheme` composable to set up internationalization. Provide custom messages for different locales, including default messages from `vitepress-openapi` and your own key-value pairs. All values are optional.

```vue
<script setup lang="ts">
import { useTheme, locales } from 'vitepress-openapi/client'

useTheme({
  i18n: {
    locale: 'en', // en | es | ja | pt-BR | zh | string
    fallbackLocale: 'en', // en | es | ja | pt-BR | zh | string
    messages: {
      en: {
        ...locales.en,
        'custom i18n key': 'Custom i18n value',
      },
      es: {
        ...locales.es,
        'custom i18n key': 'Valor personalizado i18n',
      },
      ja: {
        ...locales.ja,
        'custom i18n key': 'カスタムi18n値',
      },
      'pt-BR': {
        ...locales['pt-BR'],
        'custom i18n key': 'Valor personalizado i18n',
      },
      zh: {
        ...locales.zh,
        'custom i18n key': '自定义国际化值',
      },
    },
    availableLocales: [
      { code: 'en', label: 'English' },
      { code: 'es', label: 'Español' },
      { code: 'ja', label: 'Japanese' },
      { code: 'pt-BR', label: 'Português (Brasil)' },
      { code: 'zh', label: '中文' },
    ],
  },
})
</script>

<!-- OASpec component or OAOperation component -->
```

--------------------------------

### Render All Operations Globally

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/pages/by-spec.md

Use the `OASpec` component in a Markdown file to render all operations when the OpenAPI Specification is configured globally using `useOpenapi` in your theme's index file.

```markdown
---
aside: false
outline: false
title: vitepress-openapi
---

<OASpec />
```

--------------------------------

### Configure markdown-it operationLink Plugin

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/operation-links.md

Configure the operationLink plugin for markdown-it using the useTheme composable in your theme's index file. Options include linkPrefix, transformHref, and createOperationLinkHtml.

```javascript
import { useTheme } from 'vitepress-openapi/client'

useTheme({
  markdown: {
    operationLink: {
      linkPrefix: '/operations/',
      transformHref: (href) => href.replace('/operations/', '/api/'),
      createOperationLinkHtml: (href, method, title) => `<a href="${href}" class="operation-link">${title} (${method})</a>`,
    },
  },
})
```

--------------------------------

### Import Sandbox Component

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/sandbox/index.md

Import the Sandbox component from its path. This component is used to render the sandbox environment.

```vue
<script setup lang="ts">
import Sandbox from '../.vitepress/theme/components/sandbox/Sandbox.vue'
</script>
```

--------------------------------

### Storage Configuration API

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/composables/useTheme.md

API endpoints for managing storage configuration, including localStorage prefix and authentication persistence.

```APIDOC
## Storage Configuration API

### Description
APIs for setting and getting storage configuration, including localStorage prefix and authentication persistence.

### Endpoints

#### `setStorageConfig`

##### Description
Sets the storage configuration.

##### Method
POST

##### Endpoint
`/storage/config`

### `getStoragePrefix`

##### Description
Returns the current localStorage key prefix.

##### Method
GET

##### Endpoint
`/storage/config/prefix`

### `getStoragePersistAuth`

##### Description
Returns whether auth values are persisted to localStorage.

##### Method
GET

##### Endpoint
`/storage/config/persist-auth`
```

--------------------------------

### Generate Tag Pages with Paths Loader

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/pages/by-tag.md

Use a paths loader file to dynamically generate pages for each tag based on the OpenAPI specification. This requires importing the spec and mapping tag names to page parameters.

```javascript
import { usePaths } from 'vitepress-openapi'
import spec from '../public/openapi.json' with { type: 'json' }

export default {
    paths() {
        return usePaths({ spec })
            .getTags()
            .map(({ name }) => {
                return {
                    params: {
                        tag: name,
                        pageTitle: `${name} - vitepress-openapi`,
                    },
                }
            })
    },
}
```

--------------------------------

### Render Operations from Multiple Specs

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/multiple-specs.md

Import multiple OpenAPI JSON files and use the OAOperation component to render operations from each spec. Pass the imported spec object to the `:spec` prop for secondary specs.

```vue
<script setup lang="ts">
import defaultSpec from './openapi.json'
import schemasSpec from './openapi-schemas.json'
</script>

::: info
Using [default spec](../public/openapi.json)
:::

<OAOperation operationId="getAllArtists" />

---

::: info
Using [schemas spec](../public/openapi-schemas.json)
:::

<OAOperation operationId="getCircularReference" :spec="schemasSpec" />
```

--------------------------------

### Playground JSON Editor Configuration

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/composables/useTheme.md

Customize the appearance and behavior of the JSON editor used in the playground, including its mode and the visibility of UI elements.

```APIDOC
## Playground JSON Editor Configuration

### Description
Configures the settings for the JSON editor component within the playground.

### Functions
#### `setPlaygroundJsonEditorMode(mode: 'text' | 'tree' | 'table')`
Sets the editing mode for the JSON editor.
- **mode** (string) - Required - The mode for the JSON editor.
- **Default Value**: `'tree'`
- **Allowed Values**: `'text'`, `'tree'`, `'table'`

#### `getPlaygroundJsonEditorMode()`
Gets the current mode of the JSON editor.
- **Returns**: `'text' | 'tree' | 'table'`

#### `setPlaygroundJsonEditorMainMenuBar(visible: boolean)`
Sets the visibility of the main menu bar in the JSON editor.
- **visible** (boolean) - Required - Whether to show the main menu bar.
- **Default Value**: `false`
- **Allowed Values**: `true`, `false`

#### `getPlaygroundJsonEditorMainMenuBar()`
Gets the visibility status of the main menu bar.
- **Returns**: `boolean`

#### `setPlaygroundJsonEditorNavigationBar(visible: boolean)`
Sets the visibility of the navigation bar in the JSON editor.
- **visible** (boolean) - Required - Whether to show the navigation bar.
- **Default Value**: `false`
- **Allowed Values**: `true`, `false`

#### `getPlaygroundJsonEditorNavigationBar()`
Gets the visibility status of the navigation bar.
- **Returns**: `boolean`

#### `setPlaygroundJsonEditorStatusBar(visible: boolean)`
Sets the visibility of the status bar in the JSON editor.
- **visible** (boolean) - Required - Whether to show the status bar.
- **Default Value**: `false`
- **Allowed Values**: `true`, `false`

#### `getPlaygroundJsonEditorStatusBar()`
Gets the visibility status of the status bar.
- **Returns**: `boolean`
```

--------------------------------

### Configure Markdown Operation Links

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/composables/useTheme.md

Customize how operation links are generated in markdown, including setting a link prefix and transforming the href.

```javascript
markdown: {
    operationLink: {
        linkPrefix: '/operations/',
        transformHref: (href) => {
            return `/example${href}`
        },
    },
    externalLinksNewTab: true,
    config: md => md,
}
```

--------------------------------

### Configure OpenAPI Globally with YAML (TypeScript)

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/guide/getting-started.md

Use TypeScript to configure OpenAPI with an inline YAML string passed to the `spec` prop of `useOpenapi` in your `.vitepress/theme/index.ts`. This method is useful for embedding specifications directly.

```typescript
// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import type { Theme } from 'vitepress'
import { theme, useOpenapi } from 'vitepress-openapi/client'
import 'vitepress-openapi/dist/style.css'

export default {
    extends: DefaultTheme,
    async enhanceApp({ app }) {
        // Set the OpenAPI specification.
        useOpenapi({
          spec: `
openapi: 3.0.4
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9

servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        "200": # status code
          description: A JSON array of user names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
`,
        })

        // Use the theme.
        theme.enhanceApp({ app })
    }
} satisfies Theme
```

--------------------------------

### Create Operation Links in Markdown

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/customizations/operation-links.md

Write links directly in Markdown using the '/operations/' prefix. The operationLink plugin will automatically convert these into OAOperationLink components with method badges.

```markdown
The [Get Artists](/operations/getAllArtists) operation retrieves all artists.
```

--------------------------------

### Render Operations by Tag (Global Config)

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/pages/by-tag.md

In a Markdown file, use the OASpec component with the 'tags' prop to display operations associated with a specific tag. This assumes the OpenAPI spec is globally configured using useOpenapi.

```markdown
---
aside: false
outline: false
title: vitepress-openapi
---

<script setup lang="ts">
import { useRoute } from 'vitepress'

const route = useRoute()

const tag = route.data.params.tag
</script>

<OASpec :tags="[tag]" hide-info hide-servers hide-paths-summary />
```

--------------------------------

### Render Operation with Local Spec Import

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/pages/by-operation.md

Markdown snippet to render an API operation by importing the OpenAPI specification directly into the Markdown file and passing it as a `spec` prop to the OAOperation component.

```markdown
---
aside: false
outline: false
title: vitepress-openapi
---

<script setup lang="ts">
import { useRoute } from 'vitepress'
import spec from '../public/openapi.json'

const route = useRoute()

const operationId = route.data.params.operationId
</script>

<OAOperation :spec="spec" :operationId="operationId" />
```

--------------------------------

### Render Operations by Tag (In Markdown)

Source: https://github.com/enzonotario/vitepress-openapi/blob/main/docs/pages/by-tag.md

Import the OpenAPI specification directly within a Markdown file and pass it as the 'spec' prop to the OASpec component, along with the desired 'tags'.

```markdown
---
aside: false
outline: false
title: vitepress-openapi
---

<script setup lang="ts">
import { useRoute } from 'vitepress'
import spec from '../public/openapi.json'

const route = useRoute()

const tag = route.data.params.tag
</script>

<OASpec :spec="spec" :tags="[tag]" hide-info hide-servers hide-paths-summary />
```