FAQ

Frequently asked questions about Laravel OpenAPI Generator

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:

1. Generate during deployment:

   php artisan openapi:generate --all
   

2. Serve static files:

   'routes' => ['enabled' => false],
   

3. Enable aggressive caching:

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

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

1. Detect the resource class
2. Extract the resource structure from toArray()
3. 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:

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

Import into Insomnia:

1. Open Insomnia
2. Application → Import/Export → Import Data
3. From File → Select insomnia-api.json
4. 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": "[e-mail]"
 * }
 */
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' => '[e-mail]',
                            '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