specdocular/laravel-openapi

Generate OpenAPI Specification for Laravel Applications

v0.7.1 2026-07-24 19:32 UTC

Requires

• php: ^8.2
• composer/class-map-generator: ^1.6
• laravel/framework: ^10.0|^11.0|^12.0
• specdocular/php-openapi: ^0.1.0
• webmozart/assert: ^1.11

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.8.0
• justinrainbow/json-schema: ^6.0
• larastan/larastan: ^3.0
• orchestra/testbench: ^8.0|^9.0|^10.0
• pestphp/pest: ^3.2
• pestphp/pest-plugin-laravel: ^3.0
• pestphp/pest-plugin-type-coverage: ^3.0
• php-standard-library/psalm-plugin: ^2.3
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.1
• phpstan/phpstan-phpunit: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpstan/phpstan-webmozart-assert: ^2.0
• psalm/plugin-laravel: ^3.0
• psalm/plugin-mockery: ^1.2
• psalm/plugin-phpunit: ^0.19.2
• rector/rector: ^2.0
• slevomat/coding-standard: ^8.15
• squizlabs/php_codesniffer: *
• vimeo/psalm: ^6.0.0

MIT

• Mohammad Alavi

• documentation
• rest
• api
• docs
• laravel
• swagger
• openapi

Published on Packagist.org on 2026-07-24 19:48 UTC

README

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

Package	Description
specdocular/php-json-schema	JSON Schema Draft 2020-12 builder
specdocular/php-openapi	Object-oriented OpenAPI builder (foundation)
specdocular/laravel-rules-to-schema	Convert Laravel validation rules to JSON Schema

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.