Add to an existing site

1. Install

npm i vitepress-openapi-docs vue-api-playground

2. Plugin config

// docs/.vitepress/config.ts
import { defineConfig } from 'vitepress'
import { openApiDocs } from 'vitepress-openapi-docs/vitepress'

export default defineConfig({
  extends: await openApiDocs({
    specs: [{ name: 'api', spec: 'docs/openapi/api.yaml', prefix: '/api' }],
  }),
})

The spec path is relative to the project root. Remote URLs (e.g. https://api.example.com/openapi.json) are also supported — fetched at build time and cached.

See Configuration reference for all available fields.

3. Theme setup

// docs/.vitepress/theme/index.ts
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import { enhanceAppWithOpenApi, OperationJumper } from 'vitepress-openapi-docs'
import specs, { defaults, prefixes } from 'virtual:vitepress-openapi-docs/specs'
import changelogs from 'virtual:vitepress-openapi-docs/changelogs'
import 'vue-api-playground/styles'
import 'vitepress-openapi-docs/styles'

export default {
  extends: DefaultTheme,
  Layout() {
    return h(DefaultTheme.Layout, null, {
      'layout-top': () => h(OperationJumper),
    })
  },
  enhanceApp({ app }) {
    enhanceAppWithOpenApi({ app, specs, changelogs, defaults, prefixes })
  },
}

Import order matters: vue-api-playground/styles first, then vitepress-openapi-docs/styles, then your overrides. Each layer expands the CSS variable cascade without losing defaults.

changelogs, defaults, and prefixes are optional - omit them if you don't use <OpenApiChangelog>, custom defaults, or multi-spec cross-linking.

The OperationJumper enables Cmd+K / Ctrl+K fuzzy search across all operations.

4. Create a landing page

The plugin generates a page per operation but not the index page for your API prefix. Create it yourself so /<prefix>/ doesn't 404:

<!-- docs/api/index.md -->
---
title: API Reference
---

<OpenApiSpec name="api" />

<OpenApiSpec> renders every operation from the spec in a single scrollable page — a good default for the landing. You can also hand-write prose around individual <OpenApiEndpoint> embeds instead; see Composing endpoints.

TIP

The scaffolder (npm create vitepress-openapi-docs@latest) creates this file automatically. This step only applies when integrating into an existing site.

5. Gitignore

Add the generated pages directory:

docs/_openapi/

6. TypeScript (optional)

Add virtual module types to tsconfig.json:

{
  "compilerOptions": {
    "types": ["vitepress-openapi-docs/virtual"]
  }
}

Or use a triple-slash directive in your theme file:

/// <reference types="vitepress-openapi-docs/virtual" />

Requirements

• Node.js >= 18
• Vue >= 3.3
• VitePress >= 1.0
• vue-api-playground >= 2.4 (peer dependency)