Common Issues

This guide covers common issues you may encounter when generating OpenAPI documentation and provides actionable solutions.

Invalid API Type Parameter

Error Message: Unknown or disabled API types: {type}. Available types: api, site, mobile, adminHTTP Response: 422 Unprocessable Entity

Cause

The requested API type is either:

Not defined in config/openapi.php
Disabled in the api_types configuration array
Misspelled in the command or query parameter

Solution

Check your configuration

Open config/openapi.php and verify the api_types array:

'api_types' => [
    'api' => [
        'enabled' => true,
        'label' => 'Public API',
    ],
    'admin' => [
        'enabled' => true,  // Make sure this is true
        'label' => 'Admin API',
    ],
],

Enable the API type

Set enabled to true for the API type you want to use.

Clear config cache

If you’re using config caching, clear it:

php artisan config:clear

Regenerate documentation

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

The legacy API type movile is automatically converted to mobile, but you should update your code to use mobile directly.

No Routes Found

Message: ⚠️ No routes found matching the specified filters

Cause

Route filtering has excluded all routes. This can happen when:

API type filters remove all matching routes
Route exclusion patterns are too broad
No routes are registered with the specified API type

Solution

Review route exclusions

Check your config/openapi.php for overly aggressive exclusion patterns:

'exclude_routes' => [
    'admin.*',      // Excludes all admin routes
    'api/internal', // Excludes internal API routes
    '_debugbar',
    'sanctum.*',
],

Action: Remove or refine patterns that might be excluding routes you want to document.

Verify API type filters

If using --api-type, ensure your routes are tagged with that API type:

// In your route file or controller
Route::get('/users', [UserController::class, 'index'])
    ->middleware(['api'])
    ->defaults('apiType', 'api');  // Must match filter

Try without filters to see all routes:

php artisan openapi:generate  # No --api-type flag

Check route registration

Verify routes are actually registered:

php artisan route:list

Look for routes that should be documented but might be missing the proper middleware or metadata.

HTTP 500 When Accessing Documentation Endpoint

Error: Failed to generate specificationHTTP Status: 500 Internal Server Error

Cause

Common causes include:

Invalid JSON in template files
Syntax errors in custom templates
Exceptions during route introspection
Memory limits exceeded with large route sets

Solution

Run generation via CLI

The CLI provides full error output:

php artisan openapi:generate

This will show the complete stack trace and error message.

Validate JSON templates

Check all templates in resources/openapi/templates/:

# Validate each JSON file
php -r "json_decode(file_get_contents('resources/openapi/templates/openapi.json'));"

Look for:

Missing commas
Trailing commas
Unclosed brackets
Invalid placeholder syntax

Enable detailed logging

Set your app to debug mode temporarily:

APP_DEBUG=true
LOG_LEVEL=debug

Then check storage/logs/laravel.log for detailed errors.

Test with minimal routes

Temporarily exclude most routes to isolate the problem:

'exclude_routes' => [
    '*',  // Exclude everything
],

Then gradually add routes back to identify which one causes the error.

For production environments, serve pre-generated static files instead of generating on-demand:

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

Then serve the static file instead of using the HTTP generation endpoint.

Placeholder Values Not Updating

Symptom: Changes to .env values (like APP_NAME, APP_URL) don’t appear in generated documentation

Cause

Laravel’s config cache is enabled, and some values are read using env() at runtime instead of from cached config.

Solution

Clear config cache

php artisan config:clear

Clear OpenAPI cache

php artisan openapi:generate --no-cache

Or generate without cache:

php artisan openapi:generate --no-cache

Prefer config over env()

Instead of changing .env values, override config values in config/openapi.php:

'info' => [
    'title' => 'My Custom API Title',  // Direct value
    'version' => config('app.version'),  // From config, not env
],

Regenerate documentation

php artisan openapi:generate

Best Practice: When using config:cache in production, always set values in config files rather than relying on runtime env() calls.

Concurrent Generation File Corruption

Symptom: Partially written or inconsistent JSON/YAML files in storage/app/public/openapi

Cause

Multiple workers or processes running openapi:generate simultaneously write to the same output files.

Solution

Use unique output paths

When running generation jobs in parallel, specify unique output files:

php artisan openapi:generate --api-type=api --output=storage/temp/openapi-api-{$timestamp}.json
php artisan openapi:generate --api-type=mobile --output=storage/temp/openapi-mobile-{$timestamp}.json

Implement command locking

Use Laravel’s command locking to prevent concurrent execution:

// In a custom command that wraps openapi:generate
public function handle()
{
    $this->mutex->execute(function () {
        $this->call('openapi:generate', ['--all' => true]);
    });
}

Use queue serialization

If running generation in queued jobs, use the SerializesModels trait and ensure jobs run one at a time:

dispatch(new GenerateOpenApiJob())->onQueue('documentation');

// Configure worker to process one job at a time
php artisan queue:work --queue=documentation --max-jobs=1

Template JSON Parsing Failures

Error: Template not found or Failed to read template or is not valid JSON

Cause

Invalid JSON syntax or missing template files in resources/openapi/templates/.

Solution

Verify template exists

Check that the template file exists:

ls -la resources/openapi/templates/

Required templates:

openapi.json
postman.json
insomnia.json

Validate JSON syntax

Use a JSON validator:

cat resources/openapi/templates/openapi.json | jq .

Common issues:

Trailing commas: "key": "value",} ❌
Missing quotes: {key: "value"} ❌
Unclosed brackets: {"key": "value" ❌

Enable validation in config

For debugging, enable output validation:

// config/openapi-templates.php
'rendering' => [
    'validate_output' => true,  // Enable validation
],

Test with default templates

Temporarily restore default templates from the package:

php artisan vendor:publish --tag=openapi-templates --force

Large Route Sets Causing Timeouts

Symptom: HTTP requests to /documentation/openapi.json timeout or return 500 errors

Cause

Generating documentation for hundreds of routes with complex FormRequest validation can exceed PHP execution time limits.

Solution

Use CLI generation and serve static files

Generate documentation offline and serve pre-built files:

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

Then configure your web server to serve the static file instead of the HTTP endpoint.

Increase PHP execution time

For the HTTP endpoint, increase time limits:

// In OpenApiController or middleware
set_time_limit(300); // 5 minutes
ini_set('max_execution_time', 300);

Use API type filters

Reduce the number of routes processed per request:

# Generate separate files for each API type
php artisan openapi:generate --api-type=api
php artisan openapi:generate --api-type=admin
php artisan openapi:generate --api-type=mobile

Optimize route exclusions

Exclude routes that don’t need documentation:

'exclude_routes' => [
    'debugbar.*',
    'sanctum.*',
    'telescope.*',
    'horizon.*',
    '_ignition.*',
    'admin/internal/*',
],

Rate Limiting or Auth Blocking Documentation Routes

HTTP Status: 401 Unauthorized, 403 Forbidden, or 429 Too Many Requests

Cause

The middleware stack for documentation routes includes authentication or rate limiting:

'routes' => [
    'middleware' => ['web', 'auth:sanctum', 'throttle:60,1'],  // ❌ Problematic
],

Solution

Use dedicated middleware stack

'routes' => [
    'enabled' => true,
    'middleware' => ['web'],  // Minimal middleware
    'prefix' => 'documentation',
],

Create custom middleware for docs

// app/Http/Middleware/AllowDocsAccess.php
public function handle($request, Closure $next)
{
    // Add your custom auth logic
    if (app()->environment('production')) {
        // Require API key or IP whitelist
        if (!$this->isAuthorized($request)) {
            abort(403);
        }
    }
    
    return $next($request);
}

// config/openapi.php
'routes' => [
    'middleware' => ['web', AllowDocsAccess::class],
],

Disable HTTP routes entirely

Generate and serve static files instead:

'routes' => [
    'enabled' => false,  // Disable HTTP generation
],

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

Stale Cache in Long-Running Workers

Symptom: Queue workers serve old documentation that doesn’t reflect recent route changes

Cause

The OpenAPI cache is enabled and has a long TTL, causing workers to serve outdated specs.

Solution

Disable cache for queue jobs

// In your queued job
public function handle(OpenApiServices $generator)
{
    $spec = $generator->generate(
        useCache: false,  // Always regenerate
        apiTypes: ['api'],
        environment: 'production'
    );
}

Or via CLI:

php artisan openapi:generate --no-cache

Reduce cache TTL

// config/openapi.php
'cache' => [
    'enabled' => true,
    'ttl' => 300,  // 5 minutes instead of hours
],

Clear cache after deployments

Add cache clearing to your deployment script:

# In deploy.sh or similar
php artisan openapi:generate --no-cache
php artisan cache:clear
php artisan queue:restart

Getting Help

If you’re still experiencing issues:

Enable verbose output:
```
php artisan openapi:generate -vvv
```
Check logs:
- storage/logs/laravel.log
- Laravel Telescope (if installed)
Report issues with:
- Laravel version
- Package version
- Full error message
- Configuration (sanitized)

Get Started

Core Concepts

Configuration

Usage Guides

Troubleshooting

Invalid API Type Parameter

Cause

Solution

No Routes Found

Cause

Solution

HTTP 500 When Accessing Documentation Endpoint

Cause

Solution

Placeholder Values Not Updating

Cause

Solution

Concurrent Generation File Corruption

Cause

Solution

Template JSON Parsing Failures

Cause

Solution

Large Route Sets Causing Timeouts

Cause

Solution

Rate Limiting or Auth Blocking Documentation Routes

Cause

Solution

Stale Cache in Long-Running Workers

Cause

Solution

Getting Help

Get Started

Core Concepts

Configuration

Usage Guides

Troubleshooting

Documentation Index

​Invalid API Type Parameter

​Cause

​Solution

​No Routes Found

​Cause

​Solution

​HTTP 500 When Accessing Documentation Endpoint

​Cause

​Solution

​Placeholder Values Not Updating

​Cause

​Solution

​Concurrent Generation File Corruption

​Cause

​Solution

​Template JSON Parsing Failures

​Cause

​Solution

​Large Route Sets Causing Timeouts

​Cause

​Solution

​Rate Limiting or Auth Blocking Documentation Routes

​Cause

​Solution

​Stale Cache in Long-Running Workers

​Cause

​Solution

​Getting Help

Invalid API Type Parameter

Cause

Solution

No Routes Found

Cause

Solution

HTTP 500 When Accessing Documentation Endpoint

Cause

Solution

Placeholder Values Not Updating

Cause

Solution

Concurrent Generation File Corruption

Cause

Solution

Template JSON Parsing Failures

Cause

Solution

Large Route Sets Causing Timeouts

Cause

Solution

Rate Limiting or Auth Blocking Documentation Routes

Cause

Solution

Stale Cache in Long-Running Workers

Cause

Solution

Getting Help