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

# Environment Variables

> All environment variables used by Laravel OpenAPI Generator

The Laravel OpenAPI Generator reads environment variables through configuration files. Set these in your `.env` file to customize behavior without modifying config files.

## Core Variables

These variables control basic API information and metadata.

<ParamField path="APP_NAME" type="string" default="Laravel">
  Your application name. Used in:

  * `openapi.info.title`: API documentation title
  * Placeholder replacement: `${{projectName}}` in URLs

  ```bash theme={null}
  APP_NAME="My Amazing API"
  ```
</ParamField>

<ParamField path="APP_URL" type="string" default="http://localhost">
  Your application's base URL. Used in:

  * `openapi.environments.base.variables.base_url`: Base environment URL
  * Server definitions for local development

  ```bash theme={null}
  APP_URL=http://localhost:8000
  ```
</ParamField>

<ParamField path="API_VERSION" type="string" default="1.0.0">
  Your API version string. Appears in:

  * `openapi.info.version`: OpenAPI specification version
  * API documentation header

  ```bash theme={null}
  API_VERSION=2.1.0
  ```
</ParamField>

***

## Contact Information

These variables define support contact details in your API documentation.

<ParamField path="API_CONTACT_NAME" type="string" default="API Support">
  Support contact name displayed in API documentation.

  ```bash theme={null}
  API_CONTACT_NAME="Engineering Team"
  ```
</ParamField>

<ParamField path="API_CONTACT_EMAIL" type="string" default="support@example.com">
  Support contact email address.

  ```bash theme={null}
  API_CONTACT_EMAIL=api-support@mycompany.com
  ```
</ParamField>

<ParamField path="API_CONTACT_URL" type="string" default="https://example.com/support">
  URL to your support portal or documentation.

  ```bash theme={null}
  API_CONTACT_URL=https://docs.mycompany.com/support
  ```
</ParamField>

***

## Cache Configuration

Control caching behavior for generated OpenAPI specifications.

<ParamField path="OPENAPI_CACHE_ENABLED" type="boolean" default="true">
  Enable or disable caching of generated specifications.

  ```bash theme={null}
  OPENAPI_CACHE_ENABLED=true
  ```

  <Info>
    Disable caching during development for immediate reflection of changes:

    ```bash theme={null}
    OPENAPI_CACHE_ENABLED=false
    ```
  </Info>
</ParamField>

<ParamField path="OPENAPI_CACHE_TTL" type="integer" default="3600">
  Cache time-to-live in seconds (default: 1 hour).

  ```bash theme={null}
  OPENAPI_CACHE_TTL=7200  # 2 hours
  ```
</ParamField>

<CodeGroup>
  ```bash Development Settings theme={null}
  # Disable caching for active development
  OPENAPI_CACHE_ENABLED=false
  ```

  ```bash Production Settings theme={null}
  # Enable with longer TTL for production
  OPENAPI_CACHE_ENABLED=true
  OPENAPI_CACHE_TTL=7200
  ```
</CodeGroup>

***

## Route Configuration

Control HTTP endpoints that serve OpenAPI documentation.

<ParamField path="OPENAPI_ROUTES_ENABLED" type="boolean" default="true">
  Enable or disable HTTP documentation endpoints.

  ```bash theme={null}
  OPENAPI_ROUTES_ENABLED=true
  ```

  <Warning>
    Set to `false` in production if you don't want to expose documentation routes.
  </Warning>
</ParamField>

<ParamField path="OPENAPI_ROUTES_PREFIX" type="string" default="documentation">
  URL prefix for documentation routes.

  ```bash theme={null}
  OPENAPI_ROUTES_PREFIX=api-docs
  ```

  Results in routes like:

  * `/api-docs/openapi.json`
  * `/api-docs/postman/collection.json`
</ParamField>

<ParamField path="OPENAPI_ROUTES_MIDDLEWARE" type="string" default="">
  Comma-separated list of middleware to apply to documentation routes.

  ```bash theme={null}
  OPENAPI_ROUTES_MIDDLEWARE="auth,admin"
  ```

  <Info>
    Empty string means no middleware. Add `auth` to require authentication for viewing docs.
  </Info>
</ParamField>

<CodeGroup>
  ```bash Public Documentation theme={null}
  # Allow anyone to access documentation
  OPENAPI_ROUTES_ENABLED=true
  OPENAPI_ROUTES_PREFIX=docs
  OPENAPI_ROUTES_MIDDLEWARE=""
  ```

  ```bash Protected Documentation theme={null}
  # Require authentication and admin role
  OPENAPI_ROUTES_ENABLED=true
  OPENAPI_ROUTES_PREFIX=api-docs
  OPENAPI_ROUTES_MIDDLEWARE="auth:sanctum,admin"
  ```

  ```bash Disabled in Production theme={null}
  # Disable all documentation routes
  OPENAPI_ROUTES_ENABLED=false
  ```
</CodeGroup>

***

## Template System

Control the JSON template engine for advanced documentation customization.

<ParamField path="OPENAPI_TEMPLATES_ENABLED" type="boolean" default="true">
  Enable or disable the template system.

  ```bash theme={null}
  OPENAPI_TEMPLATES_ENABLED=true
  ```
</ParamField>

<ParamField path="OPENAPI_TEMPLATES_DEBUG" type="boolean" default="false">
  Enable debug output for template rendering.

  ```bash theme={null}
  OPENAPI_TEMPLATES_DEBUG=true
  ```

  <Info>
    Useful for troubleshooting template rendering issues during development.
  </Info>
</ParamField>

<ParamField path="OPENAPI_TEMPLATES_VALIDATE" type="boolean" default="true">
  Validate template output against OpenAPI schema.

  ```bash theme={null}
  OPENAPI_TEMPLATES_VALIDATE=true
  ```
</ParamField>

<ParamField path="OPENAPI_TEMPLATES_CACHE" type="boolean" default="true">
  Cache rendered templates for better performance.

  ```bash theme={null}
  OPENAPI_TEMPLATES_CACHE=true
  ```
</ParamField>

<ParamField path="OPENAPI_TEMPLATE_CACHE_TTL" type="integer" default="3600">
  Template cache time-to-live in seconds.

  ```bash theme={null}
  OPENAPI_TEMPLATE_CACHE_TTL=7200
  ```
</ParamField>

<CodeGroup>
  ```bash Development Template Settings theme={null}
  # Full debugging with no caching
  OPENAPI_TEMPLATES_ENABLED=true
  OPENAPI_TEMPLATES_DEBUG=true
  OPENAPI_TEMPLATES_VALIDATE=true
  OPENAPI_TEMPLATES_CACHE=false
  ```

  ```bash Production Template Settings theme={null}
  # Optimized for performance
  OPENAPI_TEMPLATES_ENABLED=true
  OPENAPI_TEMPLATES_DEBUG=false
  OPENAPI_TEMPLATES_VALIDATE=false
  OPENAPI_TEMPLATES_CACHE=true
  OPENAPI_TEMPLATE_CACHE_TTL=7200
  ```
</CodeGroup>

***

## Test Generation

Control test script generation for Postman and Insomnia.

<ParamField path="OPENAPI_TESTS_VERBOSE" type="boolean" default="false">
  Enable verbose logging for test generation.

  ```bash theme={null}
  OPENAPI_TESTS_VERBOSE=true
  ```

  <Info>
    Helpful for debugging test script generation issues.
  </Info>
</ParamField>

***

## Complete Example: .env File

Here's a complete example showing all OpenAPI Generator environment variables:

<CodeGroup>
  ```bash .env (Development) theme={null}
  # Application
  APP_NAME="My API"
  APP_URL=http://localhost:8000

  # API Information
  API_VERSION=1.0.0
  API_CONTACT_NAME="Dev Team"
  API_CONTACT_EMAIL=dev@myapi.com
  API_CONTACT_URL=https://docs.myapi.com

  # Cache (Disabled for development)
  OPENAPI_CACHE_ENABLED=false

  # Routes (Open access)
  OPENAPI_ROUTES_ENABLED=true
  OPENAPI_ROUTES_PREFIX=docs
  OPENAPI_ROUTES_MIDDLEWARE=""

  # Templates (Debug mode)
  OPENAPI_TEMPLATES_ENABLED=true
  OPENAPI_TEMPLATES_DEBUG=true
  OPENAPI_TEMPLATES_VALIDATE=true
  OPENAPI_TEMPLATES_CACHE=false

  # Tests
  OPENAPI_TESTS_VERBOSE=true
  ```

  ```bash .env (Production) theme={null}
  # Application
  APP_NAME="Production API"
  APP_URL=https://api.mycompany.com

  # API Information
  API_VERSION=2.0.0
  API_CONTACT_NAME="API Support"
  API_CONTACT_EMAIL=support@mycompany.com
  API_CONTACT_URL=https://support.mycompany.com

  # Cache (Enabled with 2-hour TTL)
  OPENAPI_CACHE_ENABLED=true
  OPENAPI_CACHE_TTL=7200

  # Routes (Protected with auth)
  OPENAPI_ROUTES_ENABLED=true
  OPENAPI_ROUTES_PREFIX=api-docs
  OPENAPI_ROUTES_MIDDLEWARE="auth:sanctum"

  # Templates (Optimized)
  OPENAPI_TEMPLATES_ENABLED=true
  OPENAPI_TEMPLATES_DEBUG=false
  OPENAPI_TEMPLATES_VALIDATE=false
  OPENAPI_TEMPLATES_CACHE=true
  OPENAPI_TEMPLATE_CACHE_TTL=7200

  # Tests
  OPENAPI_TESTS_VERBOSE=false
  ```

  ```bash .env (Staging) theme={null}
  # Application
  APP_NAME="Staging API"
  APP_URL=https://staging.mycompany.com

  # API Information
  API_VERSION=2.0.0-beta
  API_CONTACT_NAME="QA Team"
  API_CONTACT_EMAIL=qa@mycompany.com
  API_CONTACT_URL=https://docs.mycompany.com/staging

  # Cache (Moderate caching)
  OPENAPI_CACHE_ENABLED=true
  OPENAPI_CACHE_TTL=1800

  # Routes (Protected but verbose)
  OPENAPI_ROUTES_ENABLED=true
  OPENAPI_ROUTES_PREFIX=docs
  OPENAPI_ROUTES_MIDDLEWARE="auth"

  # Templates (Debugging enabled)
  OPENAPI_TEMPLATES_ENABLED=true
  OPENAPI_TEMPLATES_DEBUG=true
  OPENAPI_TEMPLATES_VALIDATE=true
  OPENAPI_TEMPLATES_CACHE=true
  OPENAPI_TEMPLATE_CACHE_TTL=1800

  # Tests
  OPENAPI_TESTS_VERBOSE=true
  ```
</CodeGroup>

***

## Runtime vs Cached Configuration

<Warning>
  This package uses `env()` directly in some runtime code (e.g., environment generation and placeholder replacement).

  If you use `php artisan config:cache`, some environment variables may not be read at runtime. Prefer overriding configuration keys in `config/openapi.php` instead.
</Warning>

### Safe with config:cache

These are read once during config caching:

* All `openapi.php` config values
* All template system settings
* Cache and route configurations

### Requires runtime access

These may need runtime `env()` access:

* Placeholder replacement in URLs (`${{projectName}}`)
* Dynamic environment variable generation

**Solution:** Override values directly in the published config file:

```php config/openapi.php theme={null}
'info' => [
    'title' => 'My API',  // Hard-coded instead of env('APP_NAME')
    'version' => '2.0.0', // Hard-coded instead of env('API_VERSION')
],
```

***

## Quick Reference

| Variable                     | Config Key                                     | Default                         | Purpose             |
| ---------------------------- | ---------------------------------------------- | ------------------------------- | ------------------- |
| `APP_NAME`                   | `openapi.info.title`                           | `'Laravel'`                     | API title           |
| `APP_URL`                    | `openapi.environments.base.variables.base_url` | `'http://localhost'`            | Base URL            |
| `API_VERSION`                | `openapi.info.version`                         | `'1.0.0'`                       | API version         |
| `API_CONTACT_NAME`           | `openapi.info.contact.name`                    | `'API Support'`                 | Contact name        |
| `API_CONTACT_EMAIL`          | `openapi.info.contact.email`                   | `'support@example.com'`         | Contact email       |
| `API_CONTACT_URL`            | `openapi.info.contact.url`                     | `'https://example.com/support'` | Contact URL         |
| `OPENAPI_CACHE_ENABLED`      | `openapi.cache.enabled`                        | `true`                          | Enable caching      |
| `OPENAPI_CACHE_TTL`          | `openapi.cache.ttl`                            | `3600`                          | Cache TTL (seconds) |
| `OPENAPI_ROUTES_ENABLED`     | `openapi.routes.enabled`                       | `true`                          | Enable routes       |
| `OPENAPI_ROUTES_PREFIX`      | `openapi.routes.prefix`                        | `'documentation'`               | Route prefix        |
| `OPENAPI_ROUTES_MIDDLEWARE`  | `openapi.routes.middleware`                    | `''`                            | Route middleware    |
| `OPENAPI_TEMPLATES_ENABLED`  | `openapi-templates.enabled`                    | `true`                          | Enable templates    |
| `OPENAPI_TEMPLATES_DEBUG`    | `openapi-templates.rendering.debug`            | `false`                         | Debug templates     |
| `OPENAPI_TEMPLATES_VALIDATE` | `openapi-templates.rendering.validate_output`  | `true`                          | Validate output     |
| `OPENAPI_TEMPLATES_CACHE`    | `openapi-templates.rendering.cache_enabled`    | `true`                          | Cache templates     |
| `OPENAPI_TEMPLATE_CACHE_TTL` | `openapi-templates.rendering.cache_ttl`        | `3600`                          | Template cache TTL  |
| `OPENAPI_TESTS_VERBOSE`      | `openapi-tests.verbose_logging`                | `false`                         | Verbose test logs   |