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

# Configuration Reference

> Complete reference for all configuration options in openapi.php and related config files

The Laravel OpenAPI Generator uses multiple configuration files to control every aspect of documentation generation. This page documents all available options with their default values.

## Main Configuration: openapi.php

Publish with:

```bash theme={null}
php artisan vendor:publish --tag=openapi-config
```

### info

Defines the OpenAPI metadata displayed in your documentation.

<ParamField path="info.title" type="string" default="env('APP_NAME', 'Laravel API')">
  The title of your API documentation. Automatically uses your application name from `APP_NAME`.
</ParamField>

<ParamField path="info.description" type="string" default="'Complete API documentation for all application modules'">
  A description of your API that appears at the top of the documentation.
</ParamField>

<ParamField path="info.version" type="string" default="env('API_VERSION', '1.0.0')">
  The version of your API. Can be controlled via the `API_VERSION` environment variable.
</ParamField>

<ParamField path="info.contact" type="array">
  Contact information for API support.

  * `name`: Contact name (default: `env('API_CONTACT_NAME', 'API Support')`)
  * `email`: Contact email (default: `env('API_CONTACT_EMAIL', 'support@example.com')`)
  * `url`: Support URL (default: `env('API_CONTACT_URL', 'https://example.com/support')`)
</ParamField>

<ParamField path="info.license" type="array">
  License information for your API.

  * `name`: License name (default: `'MIT'`)
  * `url`: License URL (default: `'https://opensource.org/licenses/MIT'`)
</ParamField>

<CodeGroup>
  ```php Example: Custom Info theme={null}
  'info' => [
      'title' => env('APP_NAME', 'Laravel API'),
      'description' => 'Complete API documentation for all application modules',
      'version' => env('API_VERSION', '1.0.0'),
      'contact' => [
          'name' => env('API_CONTACT_NAME', 'API Support'),
          'email' => env('API_CONTACT_EMAIL', 'support@example.com'),
          'url' => env('API_CONTACT_URL', 'https://example.com/support'),
      ],
      'license' => [
          'name' => 'MIT',
          'url' => 'https://opensource.org/licenses/MIT',
      ],
  ],
  ```
</CodeGroup>

***

### servers

Defines the available API servers for different environments.

<ParamField path="servers" type="array">
  Array of server definitions. Each server has:

  * `url`: The server URL
  * `description`: Human-readable description
</ParamField>

<CodeGroup>
  ```php Default Servers theme={null}
  'servers' => [
      [
          'url' => 'http://127.0.0.1:8000',
          'description' => 'Artisan server',
      ],
      [
          'url' => 'https://localhost/${{projectName}}/public',
          'description' => 'Local Server',
      ],
      [
          'url' => 'https://${{projectName}}.com',
          'description' => 'Production Server',
      ],
  ],
  ```
</CodeGroup>

<Info>
  The `${{projectName}}` placeholder is automatically replaced with your application name during generation.
</Info>

***

### security

Defines authentication schemes available in your API.

<ParamField path="security" type="array">
  Map of security scheme names to their definitions. Each scheme supports OpenAPI 3.0 security scheme properties.
</ParamField>

<Accordion title="BearerAuth (JWT)">
  Default JWT Bearer token authentication scheme.

  ```php theme={null}
  'BearerAuth' => [
      'type' => 'http',
      'scheme' => 'bearer',
      'bearerFormat' => 'JWT',
      'description' => 'JWT Bearer Token authentication',
  ],
  ```
</Accordion>

<Accordion title="ApiKeyAuth">
  API Key authentication via custom header.

  ```php theme={null}
  'ApiKeyAuth' => [
      'type' => 'apiKey',
      'in' => 'header',
      'name' => 'X-API-Key',
      'description' => 'API Key authentication',
  ],
  ```
</Accordion>

<Note>
  You can add custom security schemes here. They will be automatically included in your OpenAPI spec and Postman/Insomnia collections.
</Note>

***

### environments

Defines hierarchical environments with variable inheritance for Postman and Insomnia collections.

<ParamField path="environments" type="array">
  Map of environment names to their configurations. Supports parent-child inheritance via the `parent` key.
</ParamField>

<Accordion title="base environment (required)">
  The base environment that all other environments inherit from.

  ```php theme={null}
  'base' => [
      'name' => 'Base Environment',
      'variables' => [
          'base_url' => env('APP_URL', 'http://localhost:8000'),
          'token' => '',
          'api_key' => '',
      ],
      'tracking_variables' => [
          'last_user_id' => '',
          'last_role_id' => '',
          'last_permission_id' => '',
      ],
  ],
  ```

  <Warning>
    `tracking_variables` should ONLY be defined in the `base` environment. These are global variables used for chaining CRUD operations across requests.
  </Warning>
</Accordion>

<Accordion title="Sub-environments">
  Child environments inherit from `base` and can override specific variables.

  ```php theme={null}
  'artisan' => [
      'name' => 'Artisan Environment',
      'parent' => 'base',
      'variables' => [
          'base_url' => 'http://127.0.0.1:8000',
          'api_key' => '__GENERATED__',
      ],
  ],

  'local' => [
      'name' => 'Local Environment',
      'parent' => 'base',
      'variables' => [
          'base_url' => 'http://localhost/${{projectName}}/public',
          'api_key' => '',
      ],
  ],

  'production' => [
      'name' => 'Production Environment',
      'parent' => 'base',
      'variables' => [
          'base_url' => 'http://${{projectName}}.com',
          'api_key' => '',
      ],
  ],
  ```
</Accordion>

<Info>
  **Tracking Variables** are used to chain CRUD operations. After creating a user, the ID is stored in `last_user_id` and can be used in subsequent requests like: `/users/{{last_user_id}}`
</Info>

***

### api\_types

Configure different API types with their own route prefixes, files, and middleware.

<ParamField path="api_types" type="array">
  Map of API type keys to their configurations. Each API type can have its own route file, prefix, middleware, and documentation folder.
</ParamField>

<CodeGroup>
  ```php Default API Types theme={null}
  'api_types' => [
      'admin' => [
          'prefix' => 'admin',
          'file' => 'api.admin.php',
          'description' => 'Admin API - Backend management endpoints',
          'folder_name' => 'API Admin',
          'icon' => '🔐',
          'middleware' => ['api'],
          'enabled' => true,
      ],
      'site' => [
          'prefix' => 'site',
          'file' => 'api.frontend.php',
          'description' => 'Frontend Public API - Public facing endpoints',
          'folder_name' => 'API Frontend',
          'icon' => '🌐',
          'middleware' => ['api'],
          'enabled' => true,
      ],
      'mobile' => [
          'prefix' => 'mobile',
          'file' => 'api.mobile.php',
          'description' => 'Mobile API - Mobile application endpoints',
          'folder_name' => 'API Mobile',
          'icon' => '📱',
          'middleware' => ['api'],
          'enabled' => true,
      ],
  ],
  ```
</CodeGroup>

**Properties:**

* `prefix`: Route prefix for this API type
* `file`: Route file name in `routes/` directory
* `description`: Description shown in documentation
* `folder_name`: Folder name in Postman/Insomnia collections
* `icon`: Emoji icon for visual identification
* `middleware`: Middleware applied to these routes
* `enabled`: Toggle to enable/disable this API type

***

### modules\_path

Base path where your modules are located (for modular architectures like Nwidart Modules).

<ParamField path="modules_path" type="string" default="base_path('Modules')">
  The absolute path to your modules directory.
</ParamField>

```php theme={null}
'modules_path' => base_path('Modules'),
```

***

### exclude\_modules

Exclude entire modules from documentation generation.

<ParamField path="exclude_modules" type="array" default="[]">
  Array of module names to exclude from scanning.
</ParamField>

```php theme={null}
'exclude_modules' => ['TestModule', 'DebugModule'],
```

***

### exclude\_module\_routes

Exclude specific route patterns within modules.

<ParamField path="exclude_module_routes" type="array" default="[]">
  Array of route patterns to exclude from specific modules.
</ParamField>

```php theme={null}
'exclude_module_routes' => [
    'User::admin/debug/*',
    'Payment::internal/*',
],
```

***

### cache

Configure caching for generated OpenAPI documents.

<ParamField path="cache.enabled" type="boolean" default="env('OPENAPI_CACHE_ENABLED', true)">
  Enable or disable caching of generated specifications.
</ParamField>

<ParamField path="cache.ttl" type="integer" default="env('OPENAPI_CACHE_TTL', 3600)">
  Cache time-to-live in seconds. Default is 1 hour (3600 seconds).
</ParamField>

<ParamField path="cache.key_prefix" type="string" default="'openapi_spec_'">
  Prefix for cache keys to avoid collisions.
</ParamField>

```php theme={null}
'cache' => [
    'enabled' => env('OPENAPI_CACHE_ENABLED', true),
    'ttl' => env('OPENAPI_CACHE_TTL', 3600), // 1 hour
    'key_prefix' => 'openapi_spec_',
],
```

***

### output\_path

Base directory for generated OpenAPI specs and collections.

<ParamField path="output_path" type="string" default="storage_path('app/public/openapi')">
  The absolute path where generated files will be saved.
</ParamField>

```php theme={null}
'output_path' => storage_path('app/public/openapi'),
```

<Info>
  Generated files will be organized in subdirectories:

  * `openapi/`: OpenAPI JSON specs
  * `postman/`: Postman collections
  * `insomnia/`: Insomnia collections
</Info>

***

### paths

Define paths to scan for models and request classes.

<ParamField path="paths.models" type="array">
  Array of namespaces where models are located. Use `{module}` placeholder for module scanning.
</ParamField>

<ParamField path="paths.requests" type="array">
  Array of namespaces where FormRequest classes are located.
</ParamField>

```php theme={null}
'paths' => [
    'models' => [
        'App\\Models',
        'Modules\\{module}\\Entities',
    ],
    'requests' => [
        'App\\Http\\Requests',
        'Modules\\{module}\\Http\\Requests',
    ],
],
```

<Note>
  The `{module}` placeholder is replaced with each module name during scanning, allowing the generator to find resources across all modules.
</Note>

***

### exclude\_routes

Exclude certain routes from documentation.

<ParamField path="exclude_routes" type="array" default="[]">
  Array of URI patterns to exclude. Supports wildcards (`*`).
</ParamField>

<CodeGroup>
  ```php Default Exclusions theme={null}
  'exclude_routes' => [
      'api/documentation/*',
      'sanctum/*',
      '_ignition/*',
      'admin/modules',
      'telescope/*',
      'horizon/*',
      // Web routes
      '*/create',        // GET /resource/create
      '*/{id}/edit',     // GET /resource/{id}/edit
      '*/{*}/edit',
  ],
  ```
</CodeGroup>

<Warning>
  By default, web-only routes like `create` and `edit` forms are excluded since they return HTML views, not API responses.
</Warning>

***

### middleware\_security\_map

Map Laravel middleware to OpenAPI security requirements.

<ParamField path="middleware_security_map" type="array">
  Map of middleware names to security scheme names defined in the `security` configuration.
</ParamField>

```php theme={null}
'middleware_security_map' => [
    'auth:sanctum' => ['BearerAuth'],
    'auth:api' => ['BearerAuth'],
    'api.key' => ['ApiKeyAuth'],
],
```

<Info>
  When a route uses mapped middleware, the corresponding security requirements are automatically added to the OpenAPI operation.
</Info>

***

### response\_examples

Define default response examples for common HTTP status codes.

<ParamField path="response_examples" type="array">
  Map of status codes to their response definitions following OpenAPI 3.0 response object schema.
</ParamField>

<Accordion title="200 - Success">
  ```php theme={null}
  '200' => [
      'description' => 'Successful operation',
      'content' => [
          'application/json' => [
              'schema' => [
                  'type' => 'object',
                  'properties' => [
                      'data' => ['type' => 'object'],
                  ],
              ],
          ],
      ],
  ],
  ```
</Accordion>

<Accordion title="201 - Created">
  ```php theme={null}
  '201' => [
      'description' => 'Resource created successfully',
      'content' => [
          'application/json' => [
              'schema' => [
                  'type' => 'object',
                  'properties' => [
                      'data' => ['type' => 'object'],
                      'message' => ['type' => 'string'],
                  ],
              ],
          ],
      ],
  ],
  ```
</Accordion>

<Accordion title="401 - Unauthenticated">
  ```php theme={null}
  '401' => [
      'description' => 'Unauthenticated',
      'content' => [
          'application/json' => [
              'schema' => [
                  '$ref' => '#/components/schemas/Error',
              ],
              'example' => [
                  'message' => 'Unauthenticated.',
              ],
          ],
      ],
  ],
  ```
</Accordion>

<Accordion title="403 - Forbidden">
  ```php theme={null}
  '403' => [
      'description' => 'Forbidden',
      'content' => [
          'application/json' => [
              'schema' => [
                  '$ref' => '#/components/schemas/Error',
              ],
              'example' => [
                  'message' => 'This action is unauthorized.',
              ],
          ],
      ],
  ],
  ```
</Accordion>

<Accordion title="404 - Not Found">
  ```php theme={null}
  '404' => [
      'description' => 'Resource Not Found',
      'content' => [
          'application/json' => [
              'schema' => [
                  '$ref' => '#/components/schemas/Error',
              ],
              'example' => [
                  'message' => 'Resource not found.',
              ],
          ],
      ],
  ],
  ```
</Accordion>

<Accordion title="422 - Validation Error">
  ```php theme={null}
  '422' => [
      'description' => 'Validation Error',
      'content' => [
          'application/json' => [
              'schema' => [
                  '$ref' => '#/components/schemas/ValidationError',
              ],
              'example' => [
                  'message' => 'The given data was invalid.',
                  'errors' => [
                      'email' => ['The email field is required.'],
                  ],
              ],
          ],
      ],
  ],
  ```
</Accordion>

<Accordion title="500 - Server Error">
  ```php theme={null}
  '500' => [
      'description' => 'Internal Server Error',
      'content' => [
          'application/json' => [
              'schema' => [
                  '$ref' => '#/components/schemas/Error',
              ],
              'example' => [
                  'message' => 'Server Error',
              ],
          ],
      ],
  ],
  ```
</Accordion>

***

### routes

Configure HTTP routes for documentation access.

<ParamField path="routes.enabled" type="boolean" default="env('OPENAPI_ROUTES_ENABLED', true)">
  Enable or disable HTTP documentation endpoints.
</ParamField>

<ParamField path="routes.prefix" type="string" default="env('OPENAPI_ROUTES_PREFIX', 'documentation')">
  URL prefix for documentation routes.
</ParamField>

<ParamField path="routes.middleware" type="array" default="explode(',', env('OPENAPI_ROUTES_MIDDLEWARE', ''))">
  Middleware to apply to documentation routes. Reads from comma-separated env variable.
</ParamField>

```php theme={null}
'routes' => [
    'enabled' => env('OPENAPI_ROUTES_ENABLED', true),
    'prefix' => env('OPENAPI_ROUTES_PREFIX', 'documentation'),
    'middleware' => explode(',', env('OPENAPI_ROUTES_MIDDLEWARE', '')),
],
```

<Info>
  Set `OPENAPI_ROUTES_MIDDLEWARE="auth,admin"` in your `.env` to protect documentation routes.
</Info>

***

## Additional Configuration Files

The package includes three additional configuration files for advanced customization:

### openapi-docs.php

Controls CRUD templates, entity metadata, and custom endpoints.

**Key sections:**

* `crud_templates`: Summary/description/response templates for CRUD actions
* `entities`: Optional metadata for entities (singular/plural, model, description)
* `custom_endpoints`: Custom documentation for non-CRUD endpoints
* `auto_detect`: Enables automatic field/relationship extraction
* `field_descriptions`: Override field descriptions
* `field_examples`: Override field examples

### openapi-templates.php

Template engine controls for JSON templates under `resources/openapi/templates/`.

**Key sections:**

* `enabled`: Toggle template system
* `paths`: Paths for generic/custom templates
* `generic_templates`: Action-to-template map
* `query_builder`: Controls query builder documentation
* `auto_detect`: Model metadata extraction toggles
* `rendering`: Debug/validate/cache rendering settings
* `examples`: Example generation settings
* `performance`: Limits and caching for metadata extraction

### openapi-tests.php

Test template definitions for Postman and Insomnia.

**Key sections:**

* `templates`: Test checks for CRUD actions
* `snippets`: Actual test scripts for Postman/Insomnia
* `custom_tests`: Overrides for endpoint-specific test scripts

<Note>
  These configuration files are published together with `openapi.php` when you run:

  ```bash theme={null}
  php artisan vendor:publish --tag=openapi-config
  ```
</Note>