Getting Started

This guide will walk you through the steps to set up and use the vitepress-openapi in your VitePress project.

Demo

• DolarApi.com
• ArgentinaDatos
• CriptoYa API

Prerequisites

Before you begin, make sure you have the following installed:

• Node.js
• VitePress
• OpenAPI Specification (Version 3)

Installation

Install the vitepress-openapi package using your package manager.

npm

npm install vitepress-openapi

yarn

yarn add vitepress-openapi

pnpm

pnpm add vitepress-openapi

bun

bun add vitepress-openapi

Usage

In your .vitepress/theme/index.[js,ts], import the theme and the CSS file.

JavaScript

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import { theme } from 'vitepress-openapi'
import 'vitepress-openapi/dist/style.css'

export default {
    extends: DefaultTheme,
    async enhanceApp({ app }) {
        theme.enhanceApp({ app }) 
    }
}

TypeScript

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

export default {
    extends: DefaultTheme,
    async enhanceApp({ app }) {
        theme.enhanceApp({ app }) 
    }
} satisfies Theme

OpenAPI Specification

To use the OpenAPI specification, you can either configure it Globally, or in a specific Markdown file.

In your .vitepress/theme/index.[js,ts] file, import the OpenAPI specification and pass it as spec prop to the useOpenapi composable.

JavaScript

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import { theme } from 'vitepress-openapi'
import { theme, useOpenapi } from 'vitepress-openapi'
import 'vitepress-openapi/dist/style.css'
    
import spec from '../../public/openapi.json'

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

        // Use the theme.
        theme.enhanceApp({ app }) 
        theme.enhanceApp({ app, openapi }) 
    }
}

TypeScript

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

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

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

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

Theme Configuration

To configure the theme, you can set the theme configuration Globally, or in a specific Markdown file.

If you are using useOpenapi in your .vitepress/theme/index.[js,ts] file, you can set the theme configuration using the config prop.

JavaScript

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import { theme, useOpenapi } from 'vitepress-openapi'
import 'vitepress-openapi/dist/style.css'
    
import spec from '../../public/openapi.json'

export default {
    extends: DefaultTheme,
    async enhanceApp({ app }) {
        // Set the OpenAPI specification.
        const openapi = useOpenapi({
            spec,
            config: { 
                // Custom theme configuration...
            }, 
        })

        // Use the theme.
        theme.enhanceApp({ app, openapi })
    }
}

TypeScript

// .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' assert { type: 'json' }

export default {
    extends: DefaultTheme,
    async enhanceApp({ app }) {
        // Set the OpenAPI specification.
        const openapi = useOpenapi({
            spec,
            config: { 
                // Custom theme configuration...
            }, 
        })

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