README

Generates Laravel application code from Open Api Specification files

Installation

You can install the package via composer:

composer require ensi/laravel-openapi-server-generator --dev

Publish the config file with:

php artisan vendor:publish --provider="Ensi\LaravelOpenApiServerGenerator\LaravelOpenApiServerGeneratorServiceProvider"

and configure all the options.

Migrating from version 0.x.x

Delete config/openapi-server-generator.php, republish it using command above and recreate desired configuration.

Version Compatibility

Basic Usage

Run php artisan openapi:generate-server. It will generate all the configured entities from you OAS3 files.
Override default_entities_to_generate configiration with php artisan openapi:generate-server -e routes,enums
Make output more versbose: php artisan openapi:generate-server -v

Overwriting templates

You can also adjust file templates according to your needs.

Find the needed template inside templates directory in this repo;
Copy it to to resources/openapi-server-generator/templates directory inside your application or configure package to use another directory via extra_templates_path option;
Change whatever you need.

Existing entities and generators

'routes' => RoutesGenerator::class

Generates laravel route file (route.php) for each endpoint in oas3->paths
The following extension properties are used by this generator:

x-lg-handler: '\App\Http\Controllers\CustomersController@create' // Optional. Path is ignored if this field is empty. You can use :: instead of @ if you want
x-lg-route-name: 'createCustomer' // Optional. Translates to `->name('createCustomer')`
x-lg-middleware: '\App\Http\Middleware\Authenticate::class,web'  // Optional. Translates to `->middleware([\App\Http\Middleware\Authenticate::class, 'web'])`
x-lg-without-middleware: '\App\Http\Middleware\Authenticate::class,web'  // Optional. Translates to `->withoutMiddleware([\App\Http\Middleware\Authenticate::class, 'web'])`

route.php file IS overriden with each generation.
You should include it in your main route file like that:

$generatedRoutes = __DIR__ . "/OpenApiGenerated/routes.php";
if (file_exists($generatedRoutes)) { // prevents your app and artisan from breaking if there is no autogenerated route file for some reason.
    require $generatedRoutes;
}

'controllers' => ControllersGenerator::class

Generates Controller class for each non-existing class specified in x-lg-handler
Supports invocable Controllers.
If several openapi paths point to several methods in one Controller/Handler then the generated class includes all of them.
If a class already exists it is NOT overriden.
Controller class IS meant to be modified after generation.

'requests' => RequestsGenerator::class

Generates Laravel Form Requests for DELETE, PATCH, POST, PUT paths
Destination must be configured with array as namespace instead of string.
E.g.

'requests' => [
    'namespace' => ["Controllers" => "Requests"]
],

This means "Get handler (x-lg-handler) namespace and replace Controllers with Requests in it"
Form Request class IS meant to be modified after generation. You can treat it as a template generated with php artisan make:request FooRequest
If the file already exists it IS NOT overriden with each generation.

Form Request class name is ucFirst(operationId). You can override it with x-lg-request-class-name
You can skip generating form request for a give route with x-lg-skip-request-generation: true directive.

When generating a request, the Laravel Validation rules for request fields are automatically generated.
Validation rules generate based on the field type and required field.
For fields whose values should only take the values of some enum, you must specify the x-lg-enum-class option. E.g.: x-lg-enum-class: 'CustomerGenderEnum'.

'enums' => EnumsGenerator::class

Generates Enum class only for enums listed in oas3->components->schemas.
Your need to specify x-enum-varnames field in each enum schema. The values are used as enum constants' names.
Destination directory is cleared before generation to make sure all unused enum classes are deleted.
Enums generator does NOT support allOf, anyOf and oneOf at the moment.

'pest_tests' => PestTestsGenerator::class

Generates Pest test file for each x-lg-handler
You can exclude oas3 path from test generation using x-lg-skip-tests-generation: true.
If a test file already exists it is NOT overriden.
Test file class IS meant to be modified after generation.

'resources' => ResourcesGenerator::class

Generates Resource file for x-lg-handler
Resource properties are generated relative to field in response, which can be set in the config

'resources' => [
    'response_key' => 'data'
],

You can also specify response_key for resource: add x-lg-resource-response-key: data in object.
When specifying response_key, you can use the "dot" syntax to specify nesting, for example data.field
You can exclude resource generation using x-lg-skip-resource-generation: true in route.
You can rename resource Class using x-lg-resource-class-name: FooResource in resource object or properties object.
If a resource file already exists it is NOT overridden.
Resource file contains a set of fields according to the specification. You also need to specify mixin DocBlock to autocomplete resource.

'policies' => PoliciesGenerator::class

Generates Laravel Policies for routes. Destination must be configured with array as namespace instead of string. E.g:

'policies' => [
    'namespace' => ["Controllers" => "Policies"]
],

The path must contain a 403 response or the policy will not be generated.
You can exclude policy generation using x-lg-skip-policy-generation: true in route.
If a policy file already exists it is NOT overridden.

Contributing

Please see CONTRIBUTING for details.

Testing

composer install
composer test

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

License

The MIT License (MIT). Please see License File for more information.

ensi / laravel-openapi-server-generator

Maintainers

Details