Multi-Version API Documentation

Configure multiple named API specifications with interactive version switching.

Overview

Many applications maintain multiple API versions simultaneously (e.g. v1, v2) or separate internal APIs from public APIs.

Geni includes native multi-document support with an interactive version switcher dropdown in the documentation portal sidebar.

Configuration

Define named versions under the apis key in config/geni.php:

config/geni.php

'apis' => [
    'v1' => [
        'title' => 'API v1 (Legacy)',
        'version' => '1.4.0',
        'description' => 'Legacy API specification for mobile clients v1.x.',
        'api_path' => 'api/v1',
    ],
    'v2' => [
        'title' => 'API v2 (Latest)',
        'version' => '2.0.0',
        'description' => 'Current production API specification.',
        'api_path' => 'api/v2',
    ],
    'internal' => [
        'title' => 'Internal Admin API',
        'version' => '1.0.0',
        'api_path' => 'api/internal',
        'routes' => function () {
            return Route::getRoutes()->getByAction('App\Http\Controllers\Admin\*');
        },
    ],
],

Generated Endpoints

When named APIs are configured, Geni automatically registers dedicated routes for each version:

Version	Interactive UI	JSON Specification	MCP Discovery Endpoint
v1	/docs/api/v1	/docs/api/v1.json	/docs/api/v1/mcp
v2	/docs/api/v2	/docs/api/v2.json	/docs/api/v2/mcp
internal	/docs/api/internal	/docs/api/internal.json	/docs/api/internal/mcp

Visiting the root /docs/api automatically redirects to the first configured API version.

Interactive Version Switcher

When > 1 APIs are defined, an interactive dropdown appears in the documentation portal sidebar:

API v2 (Latest)▼

Selecting a different version switches specifications in-place without a full page reload and updates the browser URL via history.pushState().

CLI Support

All CLI commands accept an --api option to target a specific named specification:

# Export v2 specification
php artisan geni:export --api=v2 --path=v2.json

# Check v1 specification for drift
php artisan geni:check --api=v1 --path=v1.json

# Run MCP server scoped to v2
php artisan geni:mcp:serve --api=v2