Exceptions

Overview

The Laravel OpenAPI Generator raises standard PHP and Laravel exceptions for invalid input, missing configuration, and generation errors. Understanding these exceptions helps you implement robust error handling in your application.

The package does not define custom exception classes. It uses PHP’s built-in InvalidArgumentException and generic Exception for error conditions.

Exception Types

InvalidArgumentException

Thrown when invalid input is provided to generation methods. Exception Class: \InvalidArgumentException Common Scenarios:

Invalid API Types
Invalid Environment Names
Disabled API Types

Invalid API Types

Thrown when a requested API type is unknown or disabled in configuration.

Source Location

Class: OpenApiServices
Method: validateApiTypes()
Location: src/Services/OpenApiServices.php:147-161 Code:

private function validateApiTypes(?array $types): void
{
    if (empty($types)) {
        return;
    }

    $available = array_keys($this->getEnabledApiTypes());
    $invalid = array_diff($types, $available);

    if (!empty($invalid)) {
        throw new \InvalidArgumentException(
            'Unknown or disabled API types: ' . implode(', ', $invalid)
        );
    }
}

When Thrown

Programmatic API:

use Ronu\OpenApiGenerator\Facades\OpenApiGenerator;

try {
    $spec = OpenApiGenerator::generate(
        apiTypes: ['invalid-type']
    );
} catch (\InvalidArgumentException $e) {
    // Handle: "Unknown or disabled API types: invalid-type"
    logger()->error('Invalid API type', ['error' => $e->getMessage()]);
}

Artisan Command:

php artisan openapi:generate --api-type=invalid

Output:

❌ Failed to generate specification
Unknown or disabled API types: invalid. Available types: api, mobile, admin

HTTP Controller: Location: src/Controllers/OpenApiController.php:86-90

catch (\InvalidArgumentException $e) {
    return response()->json([
        'error' => 'Invalid api_type parameter',
        'message' => $e->getMessage(),
    ], 422);
}

HTTP Request:

curl "http://localhost:8000/documentation/openapi.json?api_type=invalid"

HTTP Response (422):

{
  "error": "Invalid api_type parameter",
  "message": "Unknown or disabled API types: invalid"
}

Available API Types

To avoid this exception, use only enabled API types from your configuration:

// config/openapi.php
'api_types' => [
    'api' => [
        'prefix' => 'api',
        'enabled' => true,
    ],
    'mobile' => [
        'prefix' => 'mobile',
        'enabled' => true,
    ],
    'admin' => [
        'prefix' => 'admin',
        'enabled' => false, // This will trigger exception if requested
    ],
],

Valid API types: api, mobile
Invalid API types: admin (disabled), invalid (doesn’t exist)

Invalid Environment Names

Thrown when a requested environment is not defined in configuration.

Source Location

Class: EnvironmentGenerator
Method: getEnvironmentConfig()
Location: src/Services/EnvironmentGenerator.php:120-131 Code:

protected function getEnvironmentConfig(string $environmentName): array
{
    $envConfig = config("openapi.environments.{$environmentName}");

    if (!$envConfig) {
        throw new \InvalidArgumentException(
            "Environment '{$environmentName}' not found in config/openapi.php"
        );
    }

    return $envConfig;
}

When Thrown

Programmatic API:

use Ronu\OpenApiGenerator\Facades\OpenApiGenerator;

try {
    $spec = OpenApiGenerator::generate(
        environment: 'staging' // Not defined in config
    );
} catch (\InvalidArgumentException $e) {
    // Handle: "Environment 'staging' not found in config/openapi.php"
}

Artisan Command: The command validates and falls back to artisan with a warning:

php artisan openapi:generate --environment=staging

Output:

⚠️  Unknown environment 'staging', using 'artisan' as default

Location: src/Commands/GenerateOpenApiSpec.php:96-101 HTTP Controller:

curl "http://localhost:8000/documentation/environment/staging/postman"

HTTP Response (404):

{
  "error": "Failed to generate environment",
  "message": "Environment 'staging' not found in config/openapi.php"
}

Location: src/Controllers/OpenApiController.php:216-221

Available Environments

Define environments in your configuration:

// config/openapi.php
'environments' => [
    'base' => [
        'name' => 'Base Environment',
        'variables' => [...],
    ],
    'artisan' => [
        'name' => 'Artisan Server',
        'base_url' => 'http://127.0.0.1:8000',
        'parent' => 'base',
    ],
    'local' => [
        'name' => 'Local Server',
        'base_url' => 'http://localhost/myapp',
        'parent' => 'base',
    ],
    'production' => [
        'name' => 'Production Server',
        'base_url' => 'https://api.example.com',
        'parent' => 'base',
    ],
],

Valid environments: base, artisan, local, production
Invalid environments: staging, development, qa (unless you add them)

Generic Exceptions

Thrown for unexpected errors during generation. Exception Class: \Exception

Common Scenarios

Invalid JSON templates
Missing configuration keys
File system errors
Reflection errors (when inspecting controllers/models)

Source Locations

Artisan Command: Location: src/Commands/GenerateOpenApiSpec.php:161-170

catch (\Exception $e) {
    $this->error('❌ Failed to generate specification');
    $this->error($e->getMessage());

    if ($this->output->isVerbose()) {
        $this->error($e->getTraceAsString());
    }

    return self::FAILURE;
}

HTTP Controller: Location: src/Controllers/OpenApiController.php:91-96

catch (\Exception $e) {
    return response()->json([
        'error' => 'Failed to generate specification',
        'message' => $e->getMessage(),
    ], 500);
}

Example Scenarios

Missing Configuration:

// If config/openapi.php is not published
try {
    $spec = OpenApiGenerator::generate();
} catch (\Exception $e) {
    // Could throw if critical config is missing
}

File System Errors:

# If output directory is not writable
php artisan openapi:generate --output=/root/spec.json
# Exception: Unable to write file to /root/spec.json

Reflection Errors: If a controller class cannot be inspected (rare):

// Controller with syntax errors or missing dependencies
// May throw ReflectionException during route processing

Error Handling Best Practices

Programmatic Usage

use Ronu\OpenApiGenerator\Facades\OpenApiGenerator;
use Illuminate\Support\Facades\Log;

try {
    $spec = OpenApiGenerator::generate(
        apiTypes: request()->input('api_types'),
        environment: request()->input('environment')
    );

    return response()->json($spec);

} catch (\InvalidArgumentException $e) {
    // User input error - 422 Unprocessable Entity
    Log::warning('Invalid OpenAPI generation request', [
        'error' => $e->getMessage(),
        'input' => request()->all(),
    ]);

    return response()->json([
        'error' => 'Invalid request parameters',
        'message' => $e->getMessage(),
    ], 422);

} catch (\Exception $e) {
    // Server error - 500 Internal Server Error
    Log::error('OpenAPI generation failed', [
        'error' => $e->getMessage(),
        'trace' => $e->getTraceAsString(),
    ]);

    return response()->json([
        'error' => 'Generation failed',
        'message' => config('app.debug') ? $e->getMessage() : 'An error occurred',
    ], 500);
}

Artisan Command Handling

The command already handles exceptions gracefully:

php artisan openapi:generate --api-type=invalid

Output:

❌ Failed to generate specification
Unknown or disabled API types: invalid. Available types: api, mobile, admin

With Verbose Flag:

php artisan openapi:generate --api-type=invalid -v

Output includes stack trace for debugging.

Validation Before Generation

Validate API Types:

use Ronu\OpenApiGenerator\Services\OpenApiServices;

function validateApiTypes(array $types): bool
{
    $service = app(OpenApiServices::class);
    $available = array_keys(config('openapi.api_types'));

    return empty(array_diff($types, $available));
}

if (!validateApiTypes(['api', 'mobile'])) {
    // Handle invalid types before attempting generation
}

Validate Environments:

use Ronu\OpenApiGenerator\Services\EnvironmentGenerator;

function validateEnvironment(string $env): bool
{
    $generator = app(EnvironmentGenerator::class);
    return $generator->isValidEnvironment($env);
}

if (!validateEnvironment('staging')) {
    // Fallback to default or show error
}

Testing Exception Handling

Feature Test Example

// tests/Feature/OpenApiExceptionTest.php
namespace Tests\Feature;

use Tests\TestCase;
use Ronu\OpenApiGenerator\Facades\OpenApiGenerator;

class OpenApiExceptionTest extends TestCase
{
    /** @test */
    public function throws_exception_for_invalid_api_type()
    {
        $this->expectException(\InvalidArgumentException::class);
        $this->expectExceptionMessage('Unknown or disabled API types: invalid');

        OpenApiGenerator::generate(apiTypes: ['invalid']);
    }

    /** @test */
    public function throws_exception_for_invalid_environment()
    {
        $this->expectException(\InvalidArgumentException::class);
        $this->expectExceptionMessage("Environment 'staging' not found");

        OpenApiGenerator::generate(environment: 'staging');
    }

    /** @test */
    public function http_endpoint_returns_422_for_invalid_api_type()
    {
        $response = $this->get('/documentation/openapi.json?api_type=invalid');

        $response->assertStatus(422);
        $response->assertJson([
            'error' => 'Invalid api_type parameter',
        ]);
    }

    /** @test */
    public function command_fails_gracefully_for_invalid_input()
    {
        $this->artisan('openapi:generate', ['--api-type' => 'invalid'])
            ->expectsOutput('❌ Failed to generate specification')
            ->assertExitCode(1);
    }
}

HTTP Status Codes

When using HTTP routes, exceptions map to appropriate status codes:

Exception Type	HTTP Status	Description
`InvalidArgumentException`	422	Unprocessable Entity (invalid input)
`Exception` (generic)	500	Internal Server Error
Environment not found	404	Not Found (environment endpoint)

Location: src/Controllers/OpenApiController.php

Debugging Exceptions

Enable Verbose Logging

// config/logging.php
'channels' => [
    'openapi' => [
        'driver' => 'daily',
        'path' => storage_path('logs/openapi.log'),
        'level' => 'debug', // Set to 'debug' for detailed logs
    ],
],

Check Logs

# View recent errors
tail -f storage/logs/openapi.log

# Search for exceptions
grep -i "exception" storage/logs/openapi.log

Use Telescope

If Laravel Telescope is installed, view exceptions in the dashboard:

http://localhost:8000/telescope/exceptions

Common Solutions

Problem: Unknown API Type

Error:

Unknown or disabled API types: admin

Solution: Enable the API type in configuration:

// config/openapi.php
'api_types' => [
    'admin' => [
        'prefix' => 'admin',
        'enabled' => true, // Change to true
    ],
],

Problem: Environment Not Found

Error:

Environment 'staging' not found in config/openapi.php

Solution: Add the environment to configuration:

// config/openapi.php
'environments' => [
    // ... existing environments
    'staging' => [
        'name' => 'Staging Server',
        'base_url' => 'https://staging.example.com',
        'parent' => 'base',
    ],
],

Problem: File Write Error

Error:

Unable to write file to /path/to/output.json

Solution: Ensure directory exists and is writable:

mkdir -p storage/app/public/openapi
chmod 755 storage/app/public/openapi

Or specify a writable output path:

php artisan openapi:generate --output=./public/openapi.json

Public API

Programmatic generation API

Artisan Commands

CLI command reference

Configuration

Configure API types and environments

Testing

Test your implementation

Reference

Overview

Exception Types

InvalidArgumentException

Invalid API Types

Source Location

When Thrown

Available API Types

Invalid Environment Names

Source Location

When Thrown

Available Environments

Generic Exceptions

Common Scenarios

Source Locations

Example Scenarios

Error Handling Best Practices

Programmatic Usage

Artisan Command Handling

Validation Before Generation

Testing Exception Handling

Feature Test Example

HTTP Status Codes

Debugging Exceptions

Enable Verbose Logging

Check Logs

Use Telescope

Common Solutions

Problem: Unknown API Type

Problem: Environment Not Found

Problem: File Write Error

Public API

Artisan Commands

Configuration

Testing

Build docs developers (and LLMs) love

Reference

Documentation Index

​Overview

​Exception Types

​InvalidArgumentException

​Invalid API Types

​Source Location

​When Thrown

​Available API Types

​Invalid Environment Names

​Source Location

​When Thrown

​Available Environments

​Generic Exceptions

​Common Scenarios

​Source Locations

​Example Scenarios

​Error Handling Best Practices

​Programmatic Usage

​Artisan Command Handling

​Validation Before Generation

​Testing Exception Handling

​Feature Test Example

​HTTP Status Codes

​Debugging Exceptions

​Enable Verbose Logging

​Check Logs

​Use Telescope

​Common Solutions

​Problem: Unknown API Type

​Problem: Environment Not Found

​Problem: File Write Error

​Related Documentation

Public API

Artisan Commands

Configuration

Testing

Build docs developers (and LLMs) love

Overview

Exception Types

InvalidArgumentException

Invalid API Types

Source Location

When Thrown

Available API Types

Invalid Environment Names

Source Location

When Thrown

Available Environments

Generic Exceptions

Common Scenarios

Source Locations

Example Scenarios

Error Handling Best Practices

Programmatic Usage

Artisan Command Handling

Validation Before Generation

Testing Exception Handling

Feature Test Example

HTTP Status Codes

Debugging Exceptions

Enable Verbose Logging

Check Logs

Use Telescope

Common Solutions

Problem: Unknown API Type

Problem: Environment Not Found

Problem: File Write Error

Related Documentation