Exceptions

Exception types and error handling in the OpenAPI generator

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:

1. Invalid API Types
2. Invalid Environment Names
3. 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

1. Invalid JSON templates
2. Missing configuration keys
3. File system errors
4. 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

---

Related Documentation

Public API

Programmatic generation API

Artisan Commands

CLI command reference

Configuration

Configure API types and environments

Testing

Test your implementation