Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/charlietyn/openapi-generator/llms.txt

Use this file to discover all available pages before exploring further.

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

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

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

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

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
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]);
    });
}
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

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.
For the HTTP endpoint, increase time limits:
// In OpenApiController or middleware
set_time_limit(300); // 5 minutes
ini_set('max_execution_time', 300);
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
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

// 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

// config/openapi.php
'cache' => [
    'enabled' => true,
    'ttl' => 300,  // 5 minutes instead of hours
],
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)

Build docs developers (and LLMs) love

Get started for freeTalk to us