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

# FAQ

> Frequently asked questions about Laravel OpenAPI Generator

Answers to common questions about using Laravel OpenAPI Generator.

## General Questions

<Accordion title="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.
</Accordion>

<Accordion title="Can I disable the HTTP documentation endpoints?">
  **Yes.** You can disable HTTP endpoints entirely and serve static files instead.

  In `config/openapi.php`:

  ```php theme={null}
  'routes' => [
      'enabled' => false,  // Disable HTTP generation endpoints
  ],
  ```

  Then generate documentation files via CLI and serve them statically:

  ```bash theme={null}
  php artisan openapi:generate --output=public/api-docs/openapi.json
  ```

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

  <Note>
    This approach is recommended for production environments to avoid on-demand generation overhead.
  </Note>
</Accordion>

<Accordion title="Can I customize the output structure?">
  **Yes.** You have multiple customization options:

  **1. Custom endpoint metadata** via `config/openapi-docs.php`:

  ```php theme={null}
  'endpoints' => [
      '/api/users' => [
          'get' => [
              'summary' => 'List all users',
              'tags' => ['Users'],
              'x-custom-field' => 'value',
          ],
      ],
  ],
  ```

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

  ```bash theme={null}
  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`:

  ```php theme={null}
  'info' => [
      'title' => 'My Custom API',
      'description' => 'Custom description',
      'version' => '2.0.0',
  ],
  'servers' => [
      [
          'url' => 'https://api.example.com',
          'description' => 'Production Server',
      ],
  ],
  ```
</Accordion>

<Accordion title="Does it support multiple API types?">
  **Yes.** You can define and filter by multiple API types.

  **Configuration** (`config/openapi.php`):

  ```php theme={null}
  '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:

  ```php theme={null}
  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:

  ```bash theme={null}
  # 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:

  ```bash theme={null}
  # 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
  ```
</Accordion>

***

## Performance & Caching

<Accordion title="How do I improve generation performance?">
  Several optimization strategies are available:

  **1. Enable caching**:

  ```php theme={null}
  // config/openapi.php
  'cache' => [
      'enabled' => true,
      'ttl' => 3600, // 1 hour
  ],
  ```

  **2. Use API type filters**:

  ```bash theme={null}
  # Generate smaller, focused specs
  php artisan openapi:generate --api-type=api
  ```

  **3. Exclude unnecessary routes**:

  ```php theme={null}
  'exclude_routes' => [
      'debugbar.*',
      'telescope.*',
      'horizon.*',
      '_ignition.*',
      'admin/internal/*',
  ],
  ```

  **4. Generate offline and serve static files**:

  ```bash theme={null}
  php artisan openapi:generate --output=public/docs/openapi.json
  ```

  **5. Use queue workers for generation**:

  ```php theme={null}
  dispatch(new GenerateOpenApiSpecJob());
  ```

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

<Accordion title="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**:

  ```bash theme={null}
  # CLI
  php artisan openapi:generate --no-cache

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

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

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

    ```php theme={null}
    'cache' => [
        'enabled' => env('OPENAPI_CACHE_ENABLED', app()->environment('production')),
        'ttl' => env('OPENAPI_CACHE_TTL', 300),
    ],
    ```
  </Note>
</Accordion>

<Accordion title="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**:
     ```bash theme={null}
     php artisan openapi:generate --all
     ```

  2. **Serve static files**:
     ```php theme={null}
     'routes' => ['enabled' => false],
     ```

  3. **Enable aggressive caching**:
     ```php theme={null}
     '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.
</Accordion>

***

## Compatibility

<Accordion title="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:

  ```bash theme={null}
  composer show ronu/laravel-openapi-generator
  ```
</Accordion>

<Accordion title="Does it work with API Resources?">
  **Yes.** The package can introspect Laravel API Resources.

  When your controller returns a resource:

  ```php theme={null}
  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:

  ```php theme={null}
  /**
   * @return UserResource
   */
  public function show(User $user)
  {
      return new UserResource($user);
  }
  ```

  Or use metadata configuration:

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

<Accordion title="Can I use it with Sanctum/Passport authentication?">
  **Yes.** The package automatically detects auth middleware and adds security schemes.

  **Sanctum** (automatically detected):

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

  Generated security definition:

  ```json theme={null}
  {
    "components": {
      "securitySchemes": {
        "sanctum": {
          "type": "http",
          "scheme": "bearer",
          "bearerFormat": "token"
        }
      }
    },
    "security": [
      {"sanctum": []}
    ]
  }
  ```

  **Custom configuration**:

  ```php theme={null}
  // config/openapi.php
  'security' => [
      'bearerAuth' => [
          'type' => 'http',
          'scheme' => 'bearer',
          'bearerFormat' => 'JWT',
      ],
      'apiKey' => [
          'type' => 'apiKey',
          'in' => 'header',
          'name' => 'X-API-Key',
      ],
  ],
  ```
</Accordion>

<Accordion title="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.

  <Note>
    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.
  </Note>
</Accordion>

***

## Multi-Environment & Deployment

<Accordion title="How do I handle multiple environments (dev, staging, production)?">
  The package has built-in environment support:

  **1. Define environments** in `config/openapi.php`:

  ```php theme={null}
  '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**:

  ```bash theme={null}
  php artisan openapi:generate --environment=production
  ```

  **3. Access via HTTP**:

  ```bash theme={null}
  curl https://your-app.test/documentation/openapi.json?environment=production
  ```

  **4. Generate environment files for Postman**:

  ```bash theme={null}
  php artisan openapi:generate --with-postman
  ```

  This creates:

  * `postman-env-local.json`
  * `postman-env-staging.json`
  * `postman-env-production.json`
</Accordion>

<Accordion title="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`:

  ```gitignore theme={null}
  /storage/app/public/openapi/
  /public/api-docs/
  ```

  And generate during deployment:

  ```bash theme={null}
  # In your deployment script
  php artisan openapi:generate --all --output=public/api-docs/openapi.json
  ```
</Accordion>

<Accordion title="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**:

  ```php theme={null}
  // 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**:

  ```json theme={null}
  {
    "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**:

  ```php theme={null}
  // 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(...);
  }
  ```
</Accordion>

***

## Integration & Export

<Accordion title="Can I import the generated spec into Postman/Insomnia?">
  **Yes.** The package natively supports multiple formats:

  **Generate Postman collection**:

  ```bash theme={null}
  php artisan openapi:generate --with-postman
  ```

  Or generate all formats:

  ```bash theme={null}
  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

  <Tip>
    The Insomnia workspace includes a "Minimal API Spec" tab and automated tests, making it a complete API testing solution.
  </Tip>
</Accordion>

<Accordion title="Can I use this with Swagger UI?">
  **Yes.** You can serve the generated OpenAPI spec with Swagger UI:

  **Option 1: Use existing HTTP endpoint**:

  ```html theme={null}
  <!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**:

  ```bash theme={null}
  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.
</Accordion>

<Accordion title="Can I customize request/response examples?">
  **Yes.** You have multiple ways to add custom examples:

  **1. Via docblock annotations** (if supported by your setup):

  ```php theme={null}
  /**
   * 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`):

  ```php theme={null}
  '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.
</Accordion>

***

## Getting More Help

<Tip>
  **Still have questions?**

  * Check the [Configuration Reference](/configuration/reference) for detailed options
  * Review [Usage Examples](/guides/basic-usage) for practical guides
  * Report issues or request features on GitHub
  * Join community discussions
</Tip>