README

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

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'),
        );
    }
}

2. Configure Collections

In config/openapi.php:

'collections' => [
    '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-collection 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

License

MIT. See LICENSE for details.

specdocular / laravel-openapi

Maintainers

Details