Laravel OpenAPI

Generate OpenAPI 3.1.x specifications for Laravel applications using a factory-based, "Laravel way" approach.

Requirements

• PHP 8.2 or higher
• Laravel 10, 11, or 12

Installation

composer require specdocular/laravel-openapi

The service provider is auto-discovered by Laravel. Publish the config:

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

Usage

1. Create an OpenAPI Factory

use Specdocular\LaravelOpenAPI\Factories\OpenAPIFactory;
use Specdocular\OpenAPI\Schema\Objects\OpenAPI\OpenAPI;
use Specdocular\OpenAPI\Schema\Objects\Info\Info;

class MyAPIFactory extends OpenAPIFactory
{
    public function instance(): OpenAPI
    {
        return OpenAPI::v311(
            Info::create('My API', '1.0.0')
                ->description('API documentation'),
        );
    }
}

Targeting an OpenAPI version

The target OAS version is a construction detail of the document, declared by the factory you call — not a config key. OpenAPI::v311(...) emits OpenAPI 3.1.1 (the default). To emit OpenAPI 3.2.0, call OpenAPI::v320(...) instead:

    public function instance(): OpenAPI
    {
        return OpenAPI::v320(
            Info::create('My API', '1.0.0')
                ->description('API documentation'),
        );
    }

Both factories take the same Info and are otherwise interchangeable; the version lives with the document because it co-varies with how the document is built.

2. Configure Documents

In config/openapi.php:

'documents' => [
    'default' => [
        'openapi' => MyAPIFactory::class,
        'directories' => [
            app_path('OpenAPI'),
        ],
    ],
],

3. Create Component Factories

Define reusable request bodies, responses, schemas, and parameters as factory classes. Place them in your configured directories and they will be auto-discovered.

4. Generate the Spec

$openApi = app(\Specdocular\LaravelOpenAPI\Generator::class)
    ->generate('default');

$json = json_encode($openApi, JSON_PRETTY_PRINT);

Features

• Factory-based component system (schemas, responses, request bodies, parameters)
• Auto-discovery of factories from configured directories
• Multi-document support for separate API versions or modules
• Route-based generation using Laravel route attributes
• Built on specdocular/php-openapi for the OpenAPI object model

Related Packages

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, the required checks, and versioning.

Security

If you discover a security vulnerability, please follow the process in SECURITY.md rather than opening a public issue.

License

MIT. See LICENSE for details.