README

Automatic OpenAPI 3.0.3, Postman, and Insomnia documentation generation for Laravel applications.

Requirements

• PHP 8.1+
• Laravel 10.x, 11.x, or 12.x
• Composer 2.x

Installation

composer require ronu/laravel-openapi-generator

Publish configuration (recommended):

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

Publish templates (optional):

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

Quickstart

Generate OpenAPI JSON:

php artisan openapi:generate

Generate all formats:

php artisan openapi:generate --all

Fetch via HTTP (when routes are enabled):

curl http://localhost:8000/documentation/openapi.json
curl http://localhost:8000/documentation/postman
curl http://localhost:8000/documentation/insomnia

Minimum viable configuration

The package works out-of-the-box, but most teams configure API types and routes in config/openapi.php:

return [
    'api_types' => [
        'admin' => [
            'prefix' => 'admin',
            'folder_name' => 'API Admin',
            'enabled' => true,
        ],
        'mobile' => [
            'prefix' => 'mobile',
            'folder_name' => 'API Mobile',
            'enabled' => true,
        ],
    ],
    'routes' => [
        'enabled' => true,
        'prefix' => 'documentation',
        'middleware' => [],
    ],
];

Common scenarios

1) Filter docs by API type

php artisan openapi:generate --all --api-type=admin --api-type=mobile

2) Expose documentation via HTTP

curl "http://localhost:8000/documentation/openapi.json?api_type=admin,mobile"

3) Add custom endpoint docs

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

Edge scenarios (short list)

• Config caching + runtime env() usage can keep old values; prefer config overrides and clear cache.
• Concurrent generation can write to the same output files; use --output for unique paths.
• Large route sets may time out on HTTP endpoints; generate via CLI and serve files from storage.

See Edge and extreme scenarios for details.

API reference

• Public API
• Artisan command reference

Troubleshooting (quick)

• Invalid api_type: Check openapi.api_types and ensure the key is enabled.
• No routes found: Review openapi.exclude_routes and API type filters.
• Placeholders not updating: Clear config cache or set config values explicitly.

Full documentation

Start here: documentation/index.md

Contributing & security

• Contributing guide: open a PR with clear scope and tests when possible.
• Security: please report vulnerabilities privately to the maintainers.

License

MIT. See LICENSE.