OpenAPI Integration

Architecture decision

The choice to use OpenAPI as the single source of truth for the API, and to drive interactive docs and tooling from it, is captured in ADR 0003: API documentation & OpenAPI strategy.

The VitePress documentation includes interactive API documentation powered by vitepress-openapi.

Overview

The OpenAPI specification is automatically loaded from /openapi/openapi.yaml and rendered as interactive documentation at /api/.

Features

• ✅ Interactive playground - Try API endpoints directly from the docs
• ✅ Auto-generated - Syncs with your OpenAPI spec automatically
• ✅ Search - Full-text search across all endpoints
• ✅ Code samples - Request/response examples in multiple languages
• ✅ Schema validation - View request/response schemas
• ✅ Authentication - Test authenticated endpoints

Configuration

Global Setup

The OpenAPI spec is configured globally in docs/.vitepress/theme/index.ts:

import { theme, useOpenapi } from 'vitepress-openapi'
import spec from '../../../openapi/openapi.yaml'

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

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

Using in Pages

To display the full API reference, use the <OASpec /> component:

---
title: API Reference
aside: false
outline: deep
---

# API Reference

<OASpec />

Displaying Individual Operations

You can also display individual operations using the <OAOperation /> component:

---
title: Get Vendors
---

# Get Vendors Endpoint

<OAOperation operationId="getVendors" />

Updating the API Docs

The API documentation is automatically generated from the bundled OpenAPI spec at /openapi/openapi.yaml.

Workflow

1. Edit domain YAML files in /openapi/domains/
2. Run the bundler (happens automatically on pre-commit):

   npm run openapi:bundle

3. Restart VitePress dev server to see changes:

   cd docs
   npm run dev

Pre-Commit Hook

The OpenAPI bundler runs automatically before each commit via the pre-commit hook in composer.json:

"pre-commit": [
    "@openapi-bundle",
    "@pint",
    "@phpcbf",
    "@phpcs",
    "@security-checker"
]

This ensures the bundled openapi.yaml is always up-to-date and committed with your changes.

Hot-Reload Behavior

What hot-reloads:

• ✅ Content changes in markdown files
• ✅ OpenAPI spec changes (after bundling)

What requires restart:

• ❌ Theme configuration changes
• ❌ New OpenAPI spec file

To restart:

# Stop server (Ctrl+C)
# Then restart
cd docs
npm run dev

Customization

Theme Configuration

You can customize the OpenAPI theme in docs/.vitepress/theme/index.ts:

useOpenapi({
    spec,
    config: {
        // Custom configuration
        hidePlayground: false,
        showBaseURL: true,
        // ... more options
    },
})

Styling

The OpenAPI components use VitePress's theme colors automatically. To customize:

1. Override CSS variables in docs/.vitepress/theme/index.ts:

import './custom.css'

2. Create docs/.vitepress/theme/custom.css:

:root {
    --vp-c-brand: #your-color;
    /* ... more overrides */
}

Resources

• vitepress-openapi Documentation
• OpenAPI Specification
• VitePress Documentation