Package Overview

Learn how Laravel OpenAPI Generator works under the hood

How It Works

Laravel OpenAPI Generator automatically scans your Laravel routes and generates comprehensive API documentation in multiple formats. The package follows a clear architecture that transforms your application’s routes into structured documentation.

Route Scanning

Automatically discovers API routes by inspecting Laravel’s routing system

Metadata Extraction

Analyzes controllers, FormRequests, and models to build complete specs

Multi-Format Output

Generates OpenAPI, Postman, and Insomnia documentation from a single source

Architecture

The package uses a layered architecture to generate documentation:

Core Components

OpenApiServices

The main orchestrator that coordinates the entire generation process.

Key Responsibilities:

• Route inspection and filtering
• API type filtering
• Cache management
• Format conversion

// Example: Generate with filters
$generator = app(OpenApiGenerator::class);

$spec = $generator->generate(
    useCache: true,
    apiTypes: ['admin', 'mobile'],
    environment: 'production',
    format: 'openapi'
);

Route Inspector

Scans Laravel’s route collection and identifies API routes based on configured prefixes.

Route Filtering Logic:

protected function inspectRoutes(): void
{
    $routes = Route::getRoutes();
    $excludePatterns = config('openapi.exclude_routes', []);

    foreach ($routes as $route) {
        $uri = $route->uri();

        // Skip excluded routes
        if ($this->shouldExcludeRoute($uri, $excludePatterns)) {
            continue;
        }

        // Only process API routes
        if (!$this->isApiRoute($uri)) {
            continue;
        }

        // Apply API type filter
        if ($this->apiTypeFilter && !$this->matchesApiTypeFilter($uri)) {
            continue;
        }

        $this->processRoute($route);
    }
}

What Gets Scanned:

• All routes starting with configured API prefixes (admin, site, mobile)
• Routes not matching exclude patterns
• Routes that pass API type filters

Documentation Resolver

Resolves documentation for each endpoint using multiple sources:

Priority System:

1. JSON Templates - Pre-defined resource documentation
2. FormRequest Rules - Validation rules from Form Request classes
3. Model Attributes - Database schema from Eloquent models
4. Generic Fallback - Default schemas when no metadata is found

$documentation = $this->docResolver->resolveForOperation(
    entity: 'users',
    action: 'create',
    controller: 'UserController',
    route: $route
);

Metadata Extractor

Extracts field definitions from FormRequests and Models.

From FormRequest:

// App/Http/Requests/StoreUserRequest.php
public function rules(): array
{
    return [
        'name' => 'required|string|max:255',
        'email' => 'required|email|unique:users',
        'role_id' => 'required|exists:roles,id',
    ];
}

Generates:

{
  "type": "object",
  "required": ["name", "email", "role_id"],
  "properties": {
    "name": {"type": "string", "maxLength": 255},
    "email": {"type": "string", "format": "email"},
    "role_id": {"type": "integer"}
  }
}

Route Processing Flow

1. Route Discovery

// config/openapi.php - API Types define route prefixes
'api_types' => [
    'admin' => [
        'prefix' => 'admin',
        'enabled' => true,
    ],
    'mobile' => [
        'prefix' => 'mobile',
        'enabled' => true,
    ],
],

The package scans routes starting with these prefixes:

• admin/* → Included in admin API type
• mobile/* → Included in mobile API type
• site/* → Included in site API type

2. URI Structure Parsing

Modular Routes

Routes following the modular pattern: /{prefix}/{module}/{entity}/{action}

POST /admin/security/users
└─ Parsed as:
   ├─ Prefix: admin
   ├─ Module: security
   ├─ Entity: users
   └─ Action: create

Detection Logic:

protected function parseUriStructure(string $uri): array
{
    $parts = explode('/', trim($uri, '/'));
    
    if ($this->isNwidartModule($parts[1])) {
        return [
            'prefix' => $parts[0],
            'module' => $parts[1],
            'entity' => $parts[2],
        ];
    }
}

Global Entity Routes

Routes for global models in App\Models:

GET /admin/roles
└─ Parsed as:
   ├─ Prefix: admin
   ├─ Module: general
   ├─ Entity: roles
   └─ Action: list

Detection Logic:

if ($this->isGlobalEntityModel($secondSegment)) {
    return [
        'prefix' => $prefix,
        'module' => 'general',
        'entity' => $secondSegment,
    ];
}

Custom Actions

Routes with custom endpoint actions:

POST /admin/api-apps/{id}/rotate
└─ Parsed as:
   ├─ Prefix: admin
   ├─ Module: general
   ├─ Entity: api-apps
   └─ Action: rotate (extracted from URI)

Action Extraction:

protected function extractActionFromUri(string $uri): string
{
    $parts = explode('/', trim($uri, '/'));
    $nonParams = array_filter($parts, 
        fn($p) => !Str::startsWith($p, '{'));
    
    // Last non-parameter segment is the action
    return end($nonParams);
}

3. Operation Building

For each route, the generator creates an OpenAPI operation:

protected function buildOperation($route, string $method): array
{
    $structure = $this->parseUriStructure($route->uri());
    $action = $this->extractAction($route->getAction(), $method);
    
    // Resolve documentation
    $documentation = $this->docResolver->resolveForOperation(
        $structure['entity'],
        $action,
        $controllerClass,
        $route
    );
    
    return [
        'operationId' => "{$structure['module']}.{$structure['entity']}.{$action}",
        'summary' => "[{$structure['prefix']}] {$summary}",
        'description' => $documentation['description'] ?? '',
        'tags' => [$structure['module']],
        'parameters' => $this->extractParameters($route),
        'requestBody' => $this->buildRequestBody($documentation),
        'responses' => $this->buildResponses($method, $action),
        'security' => $this->extractSecurity($route),
    ];
}

Caching Strategy

Generated specifications are cached to improve performance on subsequent requests.

// config/openapi.php
'cache' => [
    'enabled' => env('OPENAPI_CACHE_ENABLED', true),
    'ttl' => env('OPENAPI_CACHE_TTL', 3600), // 1 hour
    'key_prefix' => 'openapi_spec_',
],

Cache Key Structure:

// Format: openapi_spec_{apiTypes}_{environment}_{format}
'openapi_spec_admin_mobile_production_openapi'
'openapi_spec_all_artisan_postman'

Clear Cache:

php artisan openapi:clear-cache

Output Formats

OpenAPI 3.0.3

The canonical specification format. Used as the base for all other formats.

{
  "openapi": "3.0.3",
  "info": {
    "title": "My API (Admin, Mobile)",
    "version": "1.0.0"
  },
  "paths": {
    "/admin/users": {
      "get": {
        "operationId": "general.users.list",
        "tags": ["Users"]
      }
    }
  }
}

Postman Collection

Converts OpenAPI to Postman Collection v2.1 format with:

• Test scripts for CRUD operations
• Environment variable tracking
• Organized folder structure

Insomnia Workspace

Converts to Insomnia v4 workspace format with:

• Multiple environment configurations
• Request chaining support
• Folder hierarchy

All three formats are generated from the same OpenAPI specification, ensuring consistency across tools.

Next Steps

API Types

Learn how to organize routes into different API types

Environments

Configure multiple deployment environments