Common Issues

Solutions to frequently encountered problems when using Laravel OpenAPI Generator

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, admin

HTTP 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

1. 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',
       ],
   ],
   
2. Enable the API type

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

3. Clear config cache

   If you’re using config caching, clear it:

   php artisan config:clear
   
4. 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 specification

HTTP 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

1. Run generation via CLI

   The CLI provides full error output:

   php artisan openapi:generate
   

   This will show the complete stack trace and error message.

2. 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
3. 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.

4. 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

1. Clear config cache

   php artisan config:clear
   
2. Clear OpenAPI cache

   php artisan openapi:generate --no-cache
   

   Or generate without cache:

   php artisan openapi:generate --no-cache
   
3. 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
   ],
   
4. 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

1. Verify template exists

   Check that the template file exists:

   ls -la resources/openapi/templates/
   

   Required templates:

   • openapi.json
   • postman.json
   • insomnia.json
2. 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" ❌
3. Enable validation in config

   For debugging, enable output validation:

   // config/openapi-templates.php
   'rendering' => [
       'validate_output' => true,  // Enable validation
   ],
   
4. 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

1. Use dedicated middleware stack

   'routes' => [
       'enabled' => true,
       'middleware' => ['web'],  // Minimal middleware
       'prefix' => 'documentation',
   ],
   
2. 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],
   ],
   
3. 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:

1. Enable verbose output:

   php artisan openapi:generate -vvv
   

2. Check logs:

   • storage/logs/laravel.log
   • Laravel Telescope (if installed)

3. Report issues with:

   • Laravel version
   • Package version
   • Full error message
   • Configuration (sanitized)