vitepress-openapi

The vitepress-openapi package provides several specialized components for rendering OpenAPI documentation:

• OASpec: Renders a complete OpenAPI specification.
• OAOperation: Renders a specific API operation.
• OAOperationLink: Renders operation links with HTTP method badges.

When multiple examples are present, the Playground resolves which value to display using the following priority hierarchy (from highest to lowest):

1. x-playground-example at the parameter level
2. x-playground-example at the schema level
3. example at the parameter level
4. First item in examples array at the parameter level
5. example at the schema level
6. First item in examples array at the schema level

To jumpstart your project with a pre-configured VitePress setup and a sample OpenAPI spec, use the degit command to clone the starter template.

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

The usePlayground composable provides functions to manage and configure the Playground. It can be used within your .vitepress/theme/index.js file (typically inside the enhanceApp hook) or directly within any .md page/file.

To use it in your VitePress theme configuration, import it from vitepress-openapi/client and call it within enhanceApp.

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

export default {
    async enhanceApp({ app, router, siteData }) {
        const playground = usePlayground()
        // Use playground instance here
    }
}

If you are configuring your OpenAPI Specification globally in your .vitepress/theme/index.[js,ts] file using the useOpenapi composable, you can allow users to input their own server URLs in the Playground by setting allowCustomServer: true within the config.server object.

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

Once the operationLink plugin is enabled, you can create links that automatically transform into decorated operation links using the configured linkPrefix (default is /operations/).

In OpenAPI Specifications

Use standard Markdown link syntax within the description field of an OpenAPI operation. The plugin will intercept these links.

In Markdown Files

Write links directly in your .md files using the prefix. The plugin converts them into OAOperationLink components with the correct HTTP method badge.

Example Markdown:

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

You can override the default layout of OAOperation and OASpec components using Vue's scoped slots. This allows you to inject custom HTML or components into specific sections of the OpenAPI documentation, such as the header, parameters, or code samples.

To use them, use the #slot-name syntax within the component. Each slot provides access to scoped props containing the parsed OpenAPI data for that specific section.

<OAOperation operation-id="getUserById">
  <template #header="{ operation, method, path, deprecated }">
    <div class="my-header">
      <span class="method">{{ method.toUpperCase() }}</span>
      <span class="path">{{ path }}</span>
      <span v-if="deprecated" class="badge">Deprecated</span>
    </div>
  </template>
</OAOperation>

In your [tag].paths.js file, use usePaths to iterate through the tags defined in your OpenAPI specification and return the necessary route parameters for VitePress to generate the pages.

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`,
                    },
                }
            })
    },
}

To remove the Powered by VitePress OpenAPI text from the bottom of your components, apply the hide-branding prop to either the <OASpec> or <OAOperation> component.

<OASpec hide-branding />

<OAOperation hide-branding />