Configuration

Configuration

Publish the config file:

php artisan vendor:publish --tag=api-docs-config

This creates config/api-docs.php.

Full Configuration

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | Exclude Prefixes
    |--------------------------------------------------------------------------
    |
    | Route prefixes to exclude from documentation.
    | Routes starting with these prefixes will be ignored.
    |
    */
    'exclude_prefixes' => [
        '_',
        'sanctum',
        'telescope',
        'horizon',
        'storage',
        'mcp',
    ],

    /*
    |--------------------------------------------------------------------------
    | Variable Scope
    |--------------------------------------------------------------------------
    |
    | Controls where Postman variables are stored and which setter is used
    | in test scripts.
    |
    | Supported: "collection", "environment"
    |
    | "collection"   - Variables stored in collection JSON, scripts use
    |                  pm.collectionVariables.set, no environment file generated.
    | "environment"  - Variables stored in environment JSON, scripts use
    |                  pm.environment.set, environment file generated.
    |
    */
    'variable_scope' => 'collection',

    /*
    |--------------------------------------------------------------------------
    | Custom Variables
    |--------------------------------------------------------------------------
    |
    | Additional variables to include in the Postman collection.
    |
    */
    'variables' => [
        // 'CUSTOM_VAR' => 'value',
    ],

    /*
    |--------------------------------------------------------------------------
    | Postman Environments
    |--------------------------------------------------------------------------
    |
    | Define Postman environments to generate separate environment files.
    | Each environment will be exported as a .postman_environment.json file.
    | Environment files are only generated when variable_scope is "environment".
    |
    */
    'environments' => [
        'local' => [
            'API_URL' => env('API_URL', 'http://localhost'),
            'BEARER_TOKEN' => '',
        ],
        // 'staging' => [
        //     'API_URL' => 'https://staging-api.example.com',
        //     'BEARER_TOKEN' => '',
        // ],
        // 'production' => [
        //     'API_URL' => 'https://api.example.com',
        //     'BEARER_TOKEN' => '',
        // ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Default Headers
    |--------------------------------------------------------------------------
    |
    | Headers automatically added to all requests.
    |
    */
    'default_headers' => [
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],

    /*
    |--------------------------------------------------------------------------
    | YAML Configuration
    |--------------------------------------------------------------------------
    |
    | Path to YAML files containing API definitions.
    | Files are merged with PHP attribute definitions.
    | YAML definitions take priority over attributes.
    |
    */
    'yaml_path' => resource_path('api-docs'),

    /*
    |--------------------------------------------------------------------------
    | OpenAPI Configuration
    |--------------------------------------------------------------------------
    |
    | Settings for OpenAPI 3.x specification output.
    |
    */
    'openapi' => [
        'title' => env('APP_NAME', 'API Documentation'),
        'version' => '1.0.0',
        'description' => 'API documentation generated by ApiDocs',
        'servers' => [
            ['url' => 'https://api.example.com', 'description' => 'Production'],
            ['url' => 'https://staging-api.example.com', 'description' => 'Staging'],
        ],
        'output_format' => 'yaml',
    ],

    /*
    |--------------------------------------------------------------------------
    | Swagger UI Configuration
    |--------------------------------------------------------------------------
    |
    | Settings for the interactive Swagger UI documentation.
    |
    */
    'swagger' => [
        'enabled' => env('API_DOCS_SWAGGER_ENABLED', true),
        'path' => '/api/docs',
        'middleware' => [],
        'dark_mode' => true,
        'persist_authorization' => true,
        'token' => env('API_DOCS_SWAGGER_TOKEN'),
        'token_header' => 'X-Api-Docs-Token',
    ],

    /*
    |--------------------------------------------------------------------------
    | Output Configuration
    |--------------------------------------------------------------------------
    |
    | Default output paths for generated files.
    |
    */
    'output' => [
        'postman_path' => base_path('docs/postman'),
        'openapi_path' => base_path('docs/openapi'),
    ],
];

Configuration Options

exclude_prefixes

Array of route prefixes to exclude. Any route URI starting with these prefixes will be skipped.

'exclude_prefixes' => ['_', 'sanctum', 'admin', 'internal'],

You can also exclude via command:

php artisan api:generate --exclude=admin --exclude=internal

variable_scope

Controls where Postman variables are stored and which setter function is used in generated test scripts.

'variable_scope' => 'collection', // or 'environment'

Value	Variables stored in	Setter used in scripts	Environment files
collection	Collection JSON	pm.collectionVariables.set()	Not generated
environment	Environment JSON	pm.environment.set()	Generated

When set to collection, variables defined in the first environments entry are loaded into the collection JSON directly, and no separate environment file is generated. When set to environment, variables are stored in separate .postman_environment.json files.

variables

Additional Postman variables to include. Available in all requests using {{VARIABLE}} syntax.

'variables' => [
    'CUSTOM_VAR' => 'value',
],

environments

Define Postman environments with their variables. Each environment generates a separate .postman_environment.json file only when variable_scope is environment.

When variable_scope is collection, the first environment's variables are loaded into the collection JSON directly.

'environments' => [
    'local' => [
        'API_URL' => env('API_URL', 'http://localhost'),
        'BEARER_TOKEN' => '',
    ],
    'staging' => [
        'API_URL' => 'https://staging-api.example.com',
        'BEARER_TOKEN' => '',
    ],
],

Output when variable_scope is environment:

docs/postman/
├── {timestamp}-collection.json
├── {timestamp}-local.postman_environment.json
└── {timestamp}-staging.postman_environment.json

Output when variable_scope is collection:

docs/postman/
└── {timestamp}-collection.json

default_headers

Headers added to every request automatically.

'default_headers' => [
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
    'X-Requested-With' => 'XMLHttpRequest',
],

yaml_path

Directory containing YAML API definition files.

'yaml_path' => resource_path('api-docs'),  // resources/api-docs/

openapi

OpenAPI specification settings.

'openapi' => [
    'title' => 'My API',
    'version' => '2.0.0',
    'description' => 'Complete API documentation',
    'servers' => [
        ['url' => 'https://api.example.com', 'description' => 'Production'],
    ],
    'output_format' => 'yaml',  // or 'json'
],

output

Output directories for generated files.

'output' => [
    'postman_path' => base_path('docs/postman'),
    'openapi_path' => base_path('docs/openapi'),
],

swagger

Swagger UI settings.

'swagger' => [
    'enabled' => true,
    'path' => '/api/docs',
    'middleware' => [],
    'dark_mode' => true,
    'persist_authorization' => true,
    'token' => env('API_DOCS_SWAGGER_TOKEN'),
    'token_header' => 'X-Api-Docs-Token',
],

Option	Description
enabled	Enable/disable Swagger UI
path	URL path for Swagger UI (default: /api/docs)
middleware	Middleware to apply (e.g., ['auth'])
dark_mode	Enable dark theme
persist_authorization	Remember auth tokens in browser
token	Access token for protecting docs
token_header	Header name for token auth

Protect with token:

API_DOCS_SWAGGER_TOKEN=your-secret-token

Access: /api/docs?token=your-secret-token or header X-Api-Docs-Token: your-secret-token

Disable in production:

API_DOCS_SWAGGER_ENABLED=false

Command Options

Override config values via command line:

# Output format
php artisan api:generate --format=postman     # Only Postman
php artisan api:generate --format=openapi     # Only OpenAPI
php artisan api:generate --format=both        # Both (default)

# Custom output directory
php artisan api:generate --output=api-docs

# Custom collection name
php artisan api:generate --name="My API v2"

# OpenAPI format
php artisan api:generate --openapi-format=json

# Custom YAML path
php artisan api:generate --yaml=resources/api

# Additional exclusions
php artisan api:generate --exclude=admin --exclude=debug