FAQ

Answers to common questions about using Laravel OpenAPI Generator.

General Questions

Does this package modify my application routes?

No. The package only inspects routes to generate documentation. It does not:

Modify route definitions
Change route behavior
Add or remove routes
Affect route performance

The package reads your registered routes, analyzes their metadata (controllers, middleware, FormRequests), and generates OpenAPI specifications based on that information.Your application routes remain completely unchanged.

Can I disable the HTTP documentation endpoints?

Yes. You can disable HTTP endpoints entirely and serve static files instead.In config/openapi.php:

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

Then generate documentation files via CLI and serve them statically:

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

Access the static file at https://your-app.test/api-docs/openapi.json

This approach is recommended for production environments to avoid on-demand generation overhead.

Can I customize the output structure?

Yes. You have multiple customization options:1. Custom endpoint metadata via config/openapi-docs.php:

'endpoints' => [
    '/api/users' => [
        'get' => [
            'summary' => 'List all users',
            'tags' => ['Users'],
            'x-custom-field' => 'value',
        ],
    ],
],

2. Template customization in resources/openapi/templates/:

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

Then edit:

resources/openapi/templates/openapi.json - OpenAPI spec template
resources/openapi/templates/postman.json - Postman collection template
resources/openapi/templates/insomnia.json - Insomnia workspace template

3. Configuration overrides in config/openapi.php:

'info' => [
    'title' => 'My Custom API',
    'description' => 'Custom description',
    'version' => '2.0.0',
],
'servers' => [
    [
        'url' => 'https://api.example.com',
        'description' => 'Production Server',
    ],
],

Does it support multiple API types?

Yes. You can define and filter by multiple API types.Configuration (config/openapi.php):

'api_types' => [
    'api' => [
        'enabled' => true,
        'label' => 'Public API',
    ],
    'admin' => [
        'enabled' => true,
        'label' => 'Admin API',
    ],
    'mobile' => [
        'enabled' => true,
        'label' => 'Mobile API',
    ],
    'site' => [
        'enabled' => true,
        'label' => 'Web API',
    ],
],

Tag routes with API types:

Route::get('/users', [UserController::class, 'index'])
    ->defaults('apiType', 'api');

Route::get('/admin/users', [AdminUserController::class, 'index'])
    ->defaults('apiType', 'admin');

Filter by API type when generating:

# Generate for specific API type
php artisan openapi:generate --api-type=api

# Generate for multiple API types
php artisan openapi:generate --api-type=api --api-type=mobile

# Generate for all API types
php artisan openapi:generate --all

HTTP endpoints support filtering via query parameters:

# Single API type
curl https://your-app.test/documentation/openapi.json?api_type=api

# Multiple API types (comma-separated)
curl https://your-app.test/documentation/openapi.json?api_type=api,mobile

Performance & Caching

How do I improve generation performance?

Several optimization strategies are available:1. Enable caching:

// config/openapi.php
'cache' => [
    'enabled' => true,
    'ttl' => 3600, // 1 hour
],

2. Use API type filters:

# Generate smaller, focused specs
php artisan openapi:generate --api-type=api

3. Exclude unnecessary routes:

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

4. Generate offline and serve static files:

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

5. Use queue workers for generation:

dispatch(new GenerateOpenApiSpecJob());

For large applications (100+ routes), always prefer static file generation over on-demand HTTP generation.

When should I clear the cache?

Clear the OpenAPI cache when:

Adding new routes
Modifying route definitions (paths, methods, middleware)
Updating FormRequest validation rules
Changing controller docblocks
Modifying configuration (config/openapi.php)
After deployments

How to clear:

# CLI
php artisan openapi:generate --no-cache

# Laravel cache clear (includes OpenAPI cache)
php artisan cache:clear

# In code
Cache::forget('openapi_spec_*');

In development environments, consider setting a short cache TTL (300 seconds) or disabling caching entirely:

'cache' => [
    'enabled' => env('OPENAPI_CACHE_ENABLED', app()->environment('production')),
    'ttl' => env('OPENAPI_CACHE_TTL', 300),
],

Does generation impact application performance?

Impact depends on how you use the package:✅ Minimal impact when:

Using cached specifications
Generating via CLI and serving static files
Generating in background jobs

⚠️ Potential impact when:

Generating on-demand via HTTP without caching
Processing 100+ routes with complex FormRequests
Using deep route introspection

Best practices for production:

Generate during deployment:
php artisan openapi:generate --all
Serve static files:
'routes' => ['enabled' => false],

Enable aggressive caching:

'cache' => ['enabled' => true, 'ttl' => 86400],  // 24 hours

Use CDN for documentation files: Host generated JSON/YAML files on a CDN instead of serving from your application.

Compatibility

Which Laravel versions are supported?

The package supports:

Laravel 10.x ✅
Laravel 11.x ✅

Minimum requirements:

PHP 8.1+
Composer 2.0+

Check the composer.json of the package for exact version constraints:

composer show ronu/laravel-openapi-generator

Does it work with API Resources?

Yes. The package can introspect Laravel API Resources.When your controller returns a resource:

public function show(User $user)
{
    return new UserResource($user);
}

The generator will:

Detect the resource class
Extract the resource structure from toArray()
Generate schema definitions

For better results, add docblock annotations:

/**
 * @return UserResource
 */
public function show(User $user)
{
    return new UserResource($user);
}

Or use metadata configuration:

// config/openapi-docs.php
'endpoints' => [
    '/api/users/{id}' => [
        'get' => [
            'responses' => [
                '200' => [
                    'content' => [
                        'application/json' => [
                            'schema' => [
                                '$ref' => '#/components/schemas/User',
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
],

Can I use it with Sanctum/Passport authentication?

Yes. The package automatically detects auth middleware and adds security schemes.Sanctum (automatically detected):

Route::middleware('auth:sanctum')->group(function () {
    Route::get('/user', [UserController::class, 'show']);
});

Generated security definition:

{
  "components": {
    "securitySchemes": {
      "sanctum": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "token"
      }
    }
  },
  "security": [
    {"sanctum": []}
  ]
}

Custom configuration:

// config/openapi.php
'security' => [
    'bearerAuth' => [
        'type' => 'http',
        'scheme' => 'bearer',
        'bearerFormat' => 'JWT',
    ],
    'apiKey' => [
        'type' => 'apiKey',
        'in' => 'header',
        'name' => 'X-API-Key',
    ],
],

Does it support OpenAPI 3.1?

The package currently generates OpenAPI 3.0.3 specifications.OpenAPI 3.1 support depends on:

Underlying spec library updates
Community demand

Key differences between 3.0 and 3.1:

JSON Schema 2020-12 compatibility
Webhooks support
Improved $ref handling

Most API consumers (Swagger UI, Postman, Insomnia) fully support OpenAPI 3.0.3, so compatibility is not usually an issue.

If you need OpenAPI 3.1 features, you can post-process the generated JSON with custom scripts or create a GitHub issue to request this feature.

Multi-Environment & Deployment

How do I handle multiple environments (dev, staging, production)?

The package has built-in environment support:1. Define environments in config/openapi.php:

'environments' => [
    'local' => [
        'name' => 'Local Development',
        'url' => 'http://localhost:8000',
    ],
    'staging' => [
        'name' => 'Staging',
        'url' => 'https://staging.example.com',
    ],
    'production' => [
        'name' => 'Production',
        'url' => 'https://api.example.com',
    ],
],

2. Generate for specific environment:

php artisan openapi:generate --environment=production

3. Access via HTTP:

curl https://your-app.test/documentation/openapi.json?environment=production

4. Generate environment files for Postman:

php artisan openapi:generate --with-postman

This creates:

postman-env-local.json
postman-env-staging.json
postman-env-production.json

Should I commit generated files to version control?

It depends on your workflow:✅ Commit generated files if:

You want versioned API documentation
Your CI/CD doesn’t run PHP/Composer
You distribute specs to external teams
You use Git-based documentation hosting (GitHub Pages, etc.)

❌ Don’t commit if:

You generate during deployment
Files are large and change frequently
You prefer build-time generation

Recommendation: Add to .gitignore:

/storage/app/public/openapi/
/public/api-docs/

And generate during deployment:

# In your deployment script
php artisan openapi:generate --all --output=public/api-docs/openapi.json

How do I handle multi-tenant applications?

For multi-tenant setups where each tenant has different:

API endpoints
Server URLs
API titles/descriptions

Approach 1: Generate per-tenant documentation:

// For each tenant
$tenant = Tenant::find($tenantId);

// Override config
config([
    'openapi.info.title' => "{$tenant->name} API",
    'openapi.servers.0.url' => "https://{$tenant->domain}",
]);

// Generate
$outputPath = storage_path("app/tenants/{$tenant->id}/openapi.json");
Artisan::call('openapi:generate', [
    '--output' => $outputPath,
]);

Approach 2: Dynamic server URLs in templates:

{
  "servers": [
    {
      "url": "https://{tenant}.example.com",
      "description": "Tenant-specific server",
      "variables": {
        "tenant": {
          "default": "demo",
          "description": "Your tenant subdomain"
        }
      }
    }
  ]
}

Approach 3: Serve different specs based on request:

// Custom controller
public function generateForTenant(Request $request)
{
    $tenant = $request->user()->tenant;
    
    config([
        'openapi.info.title' => "{$tenant->name} API",
        'openapi.servers' => [
            ['url' => $tenant->api_url],
        ],
    ]);
    
    return $this->generator->generate(...);
}

Integration & Export

Can I import the generated spec into Postman/Insomnia?

Yes. The package natively supports multiple formats:Generate Postman collection:

php artisan openapi:generate --with-postman

Or generate all formats:

php artisan openapi:generate --all

Generated files:

postman-api.json - Postman collection
postman-env-local.json - Environment variables
postman-env-production.json
insomnia-api.json - Insomnia workspace (with environments included)

Import into Postman:

Open Postman
File → Import
Upload postman-api.json
Import each environment file (postman-env-*.json)
Select environment from dropdown

Import into Insomnia:

Open Insomnia
Application → Import/Export → Import Data
From File → Select insomnia-api.json
Environments are automatically included

The Insomnia workspace includes a “Minimal API Spec” tab and automated tests, making it a complete API testing solution.

Can I use this with Swagger UI?

Yes. You can serve the generated OpenAPI spec with Swagger UI:Option 1: Use existing HTTP endpoint:

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css" />
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
  <script>
    SwaggerUIBundle({
      url: "https://your-app.test/documentation/openapi.json",
      dom_id: '#swagger-ui',
    });
  </script>
</body>
</html>

Option 2: Generate and serve static files:

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

Then host Swagger UI to read from /swagger/openapi.json.Option 3: Use a Laravel package:Install a Swagger UI package like l5-swagger or swagger-ui-php that can consume the generated spec.

Can I customize request/response examples?

Yes. You have multiple ways to add custom examples:1. Via docblock annotations (if supported by your setup):

/**
 * Create a new user
 * 
 * @example
 * {
 *   "name": "John Doe",
 *   "email": "john@example.com"
 * }
 */
public function store(CreateUserRequest $request)
{
    // ...
}

2. Via metadata configuration (config/openapi-docs.php):

'endpoints' => [
    '/api/users' => [
        'post' => [
            'requestBody' => [
                'content' => [
                    'application/json' => [
                        'example' => [
                            'name' => 'Jane Smith',
                            'email' => 'jane@example.com',
                            'role' => 'admin',
                        ],
                    ],
                ],
            ],
            'responses' => [
                '201' => [
                    'content' => [
                        'application/json' => [
                            'example' => [
                                'id' => 123,
                                'name' => 'Jane Smith',
                                'created_at' => '2024-01-15T10:30:00Z',
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
],

3. Via FormRequest scenarios:The package auto-generates validation examples from FormRequest rules. You can customize these by providing scenario-specific examples in your configuration.

Getting More Help

Still have questions?

Check the Configuration Reference for detailed options
Review Usage Examples for practical guides
Report issues or request features on GitHub
Join community discussions

Get Started

Core Concepts

Configuration

Usage Guides

Troubleshooting

General Questions

Performance & Caching

Compatibility

Multi-Environment & Deployment

Integration & Export

Getting More Help

​General Questions

​Performance & Caching

​Compatibility

​Multi-Environment & Deployment

​Integration & Export

​Getting More Help

General Questions

Performance & Caching

Compatibility

Multi-Environment & Deployment

Integration & Export

Getting More Help