Getting Started

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

Showcase

DolarApi.com

ArgentinaDatos

docs.criptoya.comCriptoYa API

docs.pydolarve.orgpyDolarVenezuela API

View more Add your own

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/client'
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/client'
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.

Using a JSON specification

JavaScript

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import { theme } from 'vitepress-openapi/client'
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 })
    }
}

TypeScript

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import type { Theme } from 'vitepress'
import { theme } from 'vitepress-openapi/client'
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

Using a YAML specification

The spec prop can also accept a YAML string.

JavaScript

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import { theme } from 'vitepress-openapi/client'
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 })
    }
}

TypeScript

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import type { Theme } from 'vitepress'
import { theme } from 'vitepress-openapi/client'
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

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/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: { 
                // Custom theme configuration...
            }, 
        })

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

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' with { type: 'json' }

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

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