Configuration Reference

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:

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

info

Defines the OpenAPI metadata displayed in your documentation.

info.title

string

default:"env('APP_NAME', 'Laravel API')"

The title of your API documentation. Automatically uses your application name from APP_NAME.

info.description

string

A description of your API that appears at the top of the documentation.

info.version

string

default:"env('API_VERSION', '1.0.0')"

The version of your API. Can be controlled via the API_VERSION environment variable.

info.contact

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'))

info.license

array

License information for your API.

name: License name (default: 'MIT')
url: License URL (default: 'https://opensource.org/licenses/MIT')

'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',
    ],
],

servers

Defines the available API servers for different environments.

servers

array

Array of server definitions. Each server has:

url: The server URL
description: Human-readable description

'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',
    ],
],

The ${{projectName}} placeholder is automatically replaced with your application name during generation.

security

Defines authentication schemes available in your API.

security

array

Map of security scheme names to their definitions. Each scheme supports OpenAPI 3.0 security scheme properties.

BearerAuth (JWT)

Default JWT Bearer token authentication scheme.

'BearerAuth' => [
    'type' => 'http',
    'scheme' => 'bearer',
    'bearerFormat' => 'JWT',
    'description' => 'JWT Bearer Token authentication',
],

ApiKeyAuth

API Key authentication via custom header.

'ApiKeyAuth' => [
    'type' => 'apiKey',
    'in' => 'header',
    'name' => 'X-API-Key',
    'description' => 'API Key authentication',
],

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

environments

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

environments

array

Map of environment names to their configurations. Supports parent-child inheritance via the parent key.

base environment (required)

The base environment that all other environments inherit from.

'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' => '',
    ],
],

tracking_variables should ONLY be defined in the base environment. These are global variables used for chaining CRUD operations across requests.

Sub-environments

Child environments inherit from base and can override specific variables.

'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' => '',
    ],
],

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}}

api_types

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

api_types

array

Map of API type keys to their configurations. Each API type can have its own route file, prefix, middleware, and documentation folder.

'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,
    ],
],

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

modules_path

string

default:"base_path('Modules')"

The absolute path to your modules directory.

'modules_path' => base_path('Modules'),

exclude_modules

Exclude entire modules from documentation generation.

exclude_modules

array

default:"[]"

Array of module names to exclude from scanning.

'exclude_modules' => ['TestModule', 'DebugModule'],

exclude_module_routes

Exclude specific route patterns within modules.

exclude_module_routes

array

default:"[]"

Array of route patterns to exclude from specific modules.

'exclude_module_routes' => [
    'User::admin/debug/*',
    'Payment::internal/*',
],

cache

Configure caching for generated OpenAPI documents.

cache.enabled

boolean

default:"env('OPENAPI_CACHE_ENABLED', true)"

Enable or disable caching of generated specifications.

cache.ttl

integer

default:"env('OPENAPI_CACHE_TTL', 3600)"

Cache time-to-live in seconds. Default is 1 hour (3600 seconds).

cache.key_prefix

string

default:"'openapi_spec_'"

Prefix for cache keys to avoid collisions.

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

output_path

string

default:"storage_path('app/public/openapi')"

The absolute path where generated files will be saved.

'output_path' => storage_path('app/public/openapi'),

Generated files will be organized in subdirectories:

openapi/: OpenAPI JSON specs
postman/: Postman collections
insomnia/: Insomnia collections

paths

Define paths to scan for models and request classes.

paths.models

array

Array of namespaces where models are located. Use {module} placeholder for module scanning.

paths.requests

array

Array of namespaces where FormRequest classes are located.

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

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

exclude_routes

Exclude certain routes from documentation.

exclude_routes

array

default:"[]"

Array of URI patterns to exclude. Supports wildcards (*).

'exclude_routes' => [
    'api/documentation/*',
    'sanctum/*',
    '_ignition/*',
    'admin/modules',
    'telescope/*',
    'horizon/*',
    // Web routes
    '*/create',        // GET /resource/create
    '*/{id}/edit',     // GET /resource/{id}/edit
    '*/{*}/edit',
],

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

middleware_security_map

Map Laravel middleware to OpenAPI security requirements.

middleware_security_map

array

Map of middleware names to security scheme names defined in the security configuration.

'middleware_security_map' => [
    'auth:sanctum' => ['BearerAuth'],
    'auth:api' => ['BearerAuth'],
    'api.key' => ['ApiKeyAuth'],
],

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

response_examples

Define default response examples for common HTTP status codes.

response_examples

array

Map of status codes to their response definitions following OpenAPI 3.0 response object schema.

200 - Success

'200' => [
    'description' => 'Successful operation',
    'content' => [
        'application/json' => [
            'schema' => [
                'type' => 'object',
                'properties' => [
                    'data' => ['type' => 'object'],
                ],
            ],
        ],
    ],
],

201 - Created

'201' => [
    'description' => 'Resource created successfully',
    'content' => [
        'application/json' => [
            'schema' => [
                'type' => 'object',
                'properties' => [
                    'data' => ['type' => 'object'],
                    'message' => ['type' => 'string'],
                ],
            ],
        ],
    ],
],

401 - Unauthenticated

'401' => [
    'description' => 'Unauthenticated',
    'content' => [
        'application/json' => [
            'schema' => [
                '$ref' => '#/components/schemas/Error',
            ],
            'example' => [
                'message' => 'Unauthenticated.',
            ],
        ],
    ],
],

403 - Forbidden

'403' => [
    'description' => 'Forbidden',
    'content' => [
        'application/json' => [
            'schema' => [
                '$ref' => '#/components/schemas/Error',
            ],
            'example' => [
                'message' => 'This action is unauthorized.',
            ],
        ],
    ],
],

404 - Not Found

'404' => [
    'description' => 'Resource Not Found',
    'content' => [
        'application/json' => [
            'schema' => [
                '$ref' => '#/components/schemas/Error',
            ],
            'example' => [
                'message' => 'Resource not found.',
            ],
        ],
    ],
],

422 - Validation Error

'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.'],
                ],
            ],
        ],
    ],
],

500 - Server Error

'500' => [
    'description' => 'Internal Server Error',
    'content' => [
        'application/json' => [
            'schema' => [
                '$ref' => '#/components/schemas/Error',
            ],
            'example' => [
                'message' => 'Server Error',
            ],
        ],
    ],
],

routes

Configure HTTP routes for documentation access.

routes.enabled

boolean

default:"env('OPENAPI_ROUTES_ENABLED', true)"

Enable or disable HTTP documentation endpoints.

routes.prefix

string

default:"env('OPENAPI_ROUTES_PREFIX', 'documentation')"

URL prefix for documentation routes.

routes.middleware

array

Middleware to apply to documentation routes. Reads from comma-separated env variable.

'routes' => [
    'enabled' => env('OPENAPI_ROUTES_ENABLED', true),
    'prefix' => env('OPENAPI_ROUTES_PREFIX', 'documentation'),
    'middleware' => explode(',', env('OPENAPI_ROUTES_MIDDLEWARE', '')),
],

Set OPENAPI_ROUTES_MIDDLEWARE="auth,admin" in your .env to protect documentation routes.

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

These configuration files are published together with openapi.php when you run:

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

Get Started

Core Concepts

Configuration

Usage Guides

Troubleshooting

Main Configuration: openapi.php

info

servers

security

environments

api_types

modules_path

exclude_modules

exclude_module_routes

cache

output_path

paths

exclude_routes

middleware_security_map

response_examples

routes

Additional Configuration Files

openapi-docs.php

openapi-templates.php

openapi-tests.php

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Usage Guides

Troubleshooting

Documentation Index

​Main Configuration: openapi.php

​info

​servers

​security

​environments

​api_types

​modules_path

​exclude_modules

​exclude_module_routes

​cache

​output_path

​paths

​exclude_routes

​middleware_security_map

​response_examples

​routes

​Additional Configuration Files

​openapi-docs.php

​openapi-templates.php

​openapi-tests.php

Build docs developers (and LLMs) love

Main Configuration: openapi.php

info

servers

security

environments

api_types

modules_path

exclude_modules

exclude_module_routes

cache

output_path

paths

exclude_routes

middleware_security_map

response_examples

routes

Additional Configuration Files

openapi-docs.php

openapi-templates.php

openapi-tests.php