Advanced Usage

This guide covers advanced features for customizing and optimizing your documentation generation workflow.

API Type Filtering

API types allow you to segment your routes into logical groups (e.g., admin, mobile, public). Each API type can have its own prefix, folder structure, and enable/disable toggle.

Configuring API Types

Define API types in config/openapi.php:

'api_types' => [
    'admin' => [
        'prefix' => 'admin',
        'folder_name' => 'API Admin',
        'enabled' => true,
    ],
    'mobile' => [
        'prefix' => 'mobile',
        'folder_name' => 'API Mobile',
        'enabled' => true,
    ],
    'site' => [
        'prefix' => 'api',
        'folder_name' => 'API Public',
        'enabled' => false,  // Disabled types are excluded
    ],
],

Routes are matched by the prefix value. A route like /admin/users matches the admin API type.

Filtering at Runtime

CLI
HTTP
Programmatic

# Single API type
php artisan openapi:generate --api-type=admin

# Multiple API types
php artisan openapi:generate --api-type=admin --api-type=mobile

# All formats for specific types
php artisan openapi:generate --all --api-type=admin --api-type=mobile

Filenames include the API type suffix:

openapi-admin.json
postman-mobile.json

# Single API type
curl "http://localhost:8000/documentation/openapi.json?api_type=admin"

# Multiple API types (comma-separated)
curl "http://localhost:8000/documentation/openapi.json?api_type=admin,mobile"

use Ronu\OpenApiGenerator\Services\OpenApiServices;

$service = app(OpenApiServices::class);
$service->setApiTypeFilter(['admin', 'mobile']);

$spec = $service->generate(
    useCache: true,
    apiTypes: ['admin', 'mobile'],
    environment: 'production',
    generationType: 'openapi'
);

Legacy API Type Aliases

The package normalizes the legacy alias movile to mobile for backwards compatibility. You’ll see a deprecation warning if you use it:

⚠️ API type 'movile' is deprecated. Use 'mobile' instead.

Update your commands and scripts to use mobile.

Environment Management

Environments define base URLs, authentication tokens, and other variables for different deployment stages (local, staging, production).

Configuring Environments

Define environments in config/openapi.php:

'environments' => [
    // Base environment used during generation
    'base' => [
        'app_name' => env('APP_NAME', 'Laravel API'),
        'app_url' => env('APP_URL', 'http://localhost:8000'),
    ],
    
    // Sub-environments for Postman/Insomnia
    'sub_environments' => [
        'artisan' => [
            'app_url' => 'http://localhost:8000',
        ],
        'local' => [
            'app_url' => 'http://localhost:8000',
        ],
        'production' => [
            'app_url' => 'https://api.example.com',
        ],
    ],
    
    // Tracking variables merged into all sub-environments
    'tracking_variables' => [
        'api_token' => '',
        'device_id' => '',
    ],
],

Selecting Environments

Via CLI

# Default (artisan environment)
php artisan openapi:generate

# Specify environment
php artisan openapi:generate --environment=production
php artisan openapi:generate --with-postman --environment=local

If the specified environment doesn’t exist, the generator falls back to artisan:

⚠️ Unknown environment 'staging', using 'artisan' as default

Via HTTP

curl "http://localhost:8000/documentation/postman?environment=production"

Environment Files

The generator creates separate environment files for Postman:

postman-env-artisan.json
postman-env-local.json
postman-env-production.json

Each file includes base + tracking variables merged with sub-environment values.

Tracking variables like api_token are automatically included in all environments. Define them once in tracking_variables instead of repeating them in each sub-environment.

Caching

The generator caches OpenAPI specifications to improve performance for large applications.

Cache Configuration

'cache' => [
    'enabled' => true,
    'ttl' => 3600,  // Time-to-live in seconds (1 hour)
],

Disabling Cache

php artisan openapi:generate --no-cache

$spec = $service->generate(
    useCache: false,
    apiTypes: null,
    environment: 'production',
    generationType: 'openapi'
);

When to disable caching:

During active development with frequent route changes
After adding or modifying FormRequest validation rules
In queue workers that should always regenerate fresh documentation
When testing documentation accuracy

Cached output becomes stale when you add routes, modify request validation, or update custom endpoint documentation.

Cache Keys

The generator builds cache keys from:

API type filters
Environment name
Generation type (openapi, postman, insomnia)

This means filtering by different API types creates separate cache entries.

Custom Output Paths

Override the default output directory:

Single File
Directory Override

php artisan openapi:generate --output=/custom/path/openapi.json

Specifies the exact file path for the OpenAPI specification.

Change the base output directory in config/openapi.php:

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

Or use an absolute path:

'output_path' => '/var/www/public/docs',

The generator automatically creates parent directories if they don’t exist.

Template-Driven Documentation

The template system allows you to standardize descriptions, summaries, and request/response documentation across CRUD operations.

Enabling Templates

Publish and enable template processing:

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

Configure in config/openapi-templates.php:

return [
    'enabled' => true,
    
    'paths' => [
        'generic' => resource_path('openapi/templates/generic'),
        'custom' => resource_path('openapi/templates/custom'),
    ],
    
    'generic_templates' => [
        'list' => 'list.json',
        'show' => 'show.json',
        'create' => 'create.json',
        'update' => 'update.json',
        'delete' => 'delete.json',
    ],
];

Template Structure

Generic templates define reusable documentation for standard CRUD actions:

Example: list.json

{
  "summary": "List {{entity_plural}}",
  "description": "Retrieve a paginated list of {{entity_plural}}.",
  "parameters": [
    {
      "name": "page",
      "in": "query",
      "schema": {"type": "integer"},
      "description": "Page number for pagination"
    },
    {
      "name": "per_page",
      "in": "query",
      "schema": {"type": "integer"},
      "description": "Items per page"
    }
  ]
}

Example: show.json

{
  "summary": "Get {{entity_singular}}",
  "description": "Retrieve details for a specific {{entity_singular}}.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {"type": "integer"},
      "description": "{{entity_singular}} ID"
    }
  ]
}

Custom Endpoint Documentation

For non-CRUD endpoints, define custom documentation in config/openapi-docs.php:

'custom_endpoints' => [
    'api-apps.rotate' => [
        'summary' => 'Rotate API Key',
        'description' => 'Generates a new API key for the application.',
        'request_fields' => [
            'reason' => 'Optional reason for key rotation',
        ],
        'response_description' => 'Returns the new API key and revocation timestamp.',
    ],
    'users.export' => [
        'summary' => 'Export Users',
        'description' => 'Generates a CSV export of filtered users.',
        'request_fields' => [
            'format' => 'Export format: csv, xlsx, or json',
            'filters' => 'Array of filter conditions',
        ],
    ],
],

Use the pattern entity.action for keys. The generator matches these against route names like api-apps.rotate or users.export.

Template Processing Flow

Route Introspection

The generator extracts route metadata: path, methods, parameters, FormRequests.

Template Selection

Check for custom endpoint documentation by route name
If not found, match CRUD action (list, show, create, update, delete)
Load corresponding generic template

Placeholder Replacement

Replace placeholders like {{entity_singular}} and {{entity_plural}} with actual values.

Merge with Metadata

Combine template content with extracted FormRequest validation rules and model properties.

Template ValidationInvalid JSON in template files causes generation to fail. Enable output validation during debugging:

'rendering' => [
    'validate_output' => true,
],

This adds extra validation but slows generation.

Excluding Routes

Prevent specific routes from appearing in documentation:

'exclude_routes' => [
    'horizon.*',
    'telescope.*',
    'sanctum.*',
    '_debugbar.*',
    'internal.*',
],

Patterns support wildcards. Routes matching any pattern are excluded from all generated documentation.

Programmatic Generation Advanced

For complex use cases, you can directly access generation services:

use Ronu\OpenApiGenerator\Services\OpenApiServices;
use Ronu\OpenApiGenerator\Services\PostmanCollectionGenerator;
use Ronu\OpenApiGenerator\Services\InsomniaWorkspaceGenerator;
use Ronu\OpenApiGenerator\Services\EnvironmentGenerator;

// Generate OpenAPI with full control
$openApiService = app(OpenApiServices::class);
$openApiService->setApiTypeFilter(['admin']);
$spec = $openApiService->generate(
    useCache: false,
    apiTypes: ['admin'],
    environment: 'production',
    generationType: 'openapi'
);

// Generate Postman collection from spec
$postmanGen = app(PostmanCollectionGenerator::class);
$collection = $postmanGen->generate($spec, 'production', ['admin']);

// Generate Insomnia workspace from spec
$insomniaGen = app(InsomniaWorkspaceGenerator::class);
$workspace = $insomniaGen->generate($spec, 'production', ['admin']);

// Generate environment files
$envGen = app(EnvironmentGenerator::class);
$postmanEnv = $envGen->generatePostman('production');
$insomniaEnvs = $envGen->generateInsomnia('production');

Service Responsibilities

OpenApiServices

Route introspection and filtering
Caching
OpenAPI specification assembly

PostmanCollectionGenerator

Converts OpenAPI spec to Postman Collection v2.1 format
Embeds environment variables

InsomniaWorkspaceGenerator

Converts OpenAPI spec to Insomnia v4 format
Creates workspace with spec, collection, and test tabs

EnvironmentGenerator

Merges base + tracking + sub-environment variables
Generates environment files for Postman and Insomnia

Next Steps

Common Scenarios

Real-world examples including team workflows and CI/CD integration.

Edge Cases

Handling config caching, concurrent generation, and multi-tenant deployments.

Get Started

Core Concepts

Configuration

Usage Guides

Troubleshooting

API Type Filtering

Configuring API Types

Filtering at Runtime

Legacy API Type Aliases

Environment Management

Configuring Environments

Selecting Environments

Caching

Cache Configuration

Disabling Cache

Cache Keys

Custom Output Paths

Template-Driven Documentation

Enabling Templates

Template Structure

Custom Endpoint Documentation

Template Processing Flow

Excluding Routes

Programmatic Generation Advanced

Next Steps

Common Scenarios

Edge Cases

​API Type Filtering

​Configuring API Types

​Filtering at Runtime

​Legacy API Type Aliases

​Environment Management

​Configuring Environments

​Selecting Environments

​Caching

​Cache Configuration

​Disabling Cache

​Cache Keys

​Custom Output Paths

​Template-Driven Documentation

​Enabling Templates

​Template Structure

​Custom Endpoint Documentation

​Template Processing Flow

​Excluding Routes

​Programmatic Generation Advanced

​Next Steps

Common Scenarios

Edge Cases

API Type Filtering

Configuring API Types

Filtering at Runtime

Legacy API Type Aliases

Environment Management

Configuring Environments

Selecting Environments

Caching

Cache Configuration

Disabling Cache

Cache Keys

Custom Output Paths

Template-Driven Documentation

Enabling Templates

Template Structure

Custom Endpoint Documentation

Template Processing Flow

Excluding Routes

Programmatic Generation Advanced

Next Steps