Api Generator Laravel Package

Getting Started

Install into a Laravel app that matches the package's era (Laravel 6/7, PHP 7.2–7.4) before attempting anything on a modern stack:

composer require solidry/api-generator
php artisan vendor:publish --provider="Solidry\ApiGenerator\ApiGeneratorServiceProvider"

Where to look first, in order:

1. config/api-generator.php — the published config is the real entry point. It holds the generator namespace/paths, stub locations, and the conventions (route prefix, model namespace, whether it emits requests/resources/tests) that every other step depends on.
2. php artisan list | grep -i api — the package drives generation through an artisan command; confirm the exact signature on your installed version rather than assuming, since command names shifted across releases.
3. The spec/schema input the generator consumes (a JSON or PHP array describing entities, fields, types, and relationships). This file is your API design document — everything else is derived from it.
4. vendor/solidry/api-generator/src/ — the generator classes and stubs. Reading these tells you precisely what will be written and where, which is faster than diffing afterward.

First use case: generate one resource end-to-end. Describe a single Post entity (id, title:string, body:text, published_at:datetime, author:belongsTo:User) in the spec, run the generator against a clean git tree, and inspect what lands:

• app/Models/Post.php + migration
• app/Http/Controllers/Api/PostController.php
• app/Http/Requests/*PostRequest.php
• app/Http/Resources/PostResource.php (the JSON:API serializer)
• routes/api.php additions
• a feature test hitting /api/posts

Then curl the endpoint with Accept: application/vnd.api+json and verify the payload has data.type/data.id/data.attributes, not a flat array. That single round-trip validates your config, your spec, and the JSON:API layer all at once — fix config before scaling to more entities.

Implementation Patterns

Schema-first, scaffold-once. The package is a scaffolding tool, not a runtime library. The healthy workflow is: author the spec → generate → commit the output → hand-edit. Treat subsequent regenerations as a merge problem, not a sync problem. Keep the spec file in the repo as living documentation of the API contract, but assume generated files are now yours.

Layering the generated output. Generated controllers are thin CRUD. The patterns that age well around them:

• Let the generated FormRequest own validation; move any business rules out into a service/action class so the controller stays a transport concern.
• Keep the generated JSON:API resource as the only serializer. Resist returning Eloquent models directly from new hand-written endpoints — one array response leaks through and clients written against data.attributes break on that route.
• If the generator emits a base controller or trait, extend it rather than editing it, so you can re-publish improved stubs later.

Relationship handling. Spec-driven relations generate belongsTo/hasMany methods, foreign keys, and resource relationships blocks. The useful pattern is to pair spec changes with explicit eager-loading: add $with or a scoped query so /api/posts?include=author doesn't issue N+1 queries once the dataset is real.

Contract-first with a frontend. Because the output is JSON:API, you can generate a couple of entities, hit them, and hand the real response bodies (not a hand-written spec) to the frontend team. This is the highest-value use of the package: fast, spec-correct fixtures for a client that expects included, links, and meta.

Testing as a baseline, not a suite. Generated feature tests assert status codes and payload shape. Keep them — they catch regressions when you edit resources — but they rarely cover auth, authorization policies, filtering, or sorting. Add those by hand per resource.

Integration tips:

• Register generated routes inside your existing Route::middleware('api') group rather than accepting a second prefix; you want one auth middleware stack.
• Pair with php artisan make:* for everything the generator skips (policies, observers, jobs), keeping naming consistent with what it produced so the codebase reads uniformly.
• Run the generator on a branch with a clean tree; git diff after generation is your actual review of what the tool decided.

Gotchas and Tips

Age is the dominant risk. Last release August 2020 means it predates Laravel 8's namespace changes, model factories as classes, and PHP 8. Running it against Laravel 9+ will likely fail on RouteServiceProvider namespace assumptions, $namespace property removal, or PHP 8 string/type behavior in the stubs. Validate on a throwaway Laravel 6/7 app first; if you must use it on a modern app, plan to fork the stubs rather than fight the generator.

Generated code overwrites silently. Commit before generating, and never point it at a directory containing hand-edited files you haven't committed. There is no dry-run guarantee across versions — verify whether one exists before a large regeneration.

JSON:API error responses are the usual hole. Laravel's default exception handler returns {"message": "..."} for 404/422/500, which violates the spec your success responses follow. Override render() in app/Exceptions/Handler.php to emit errors[] objects with status, title, and source.pointer for validation failures. This is the single most common source of "your API doesn't work" bug reports from JSON:API clients.

Content negotiation. Clients must send Accept: application/vnd.api+json. Decide early whether you'll return 406 for anything else (strict) or accept application/json (pragmatic). Being inconsistent between generated and hand-written routes is worse than either choice.

IDs must be strings in JSON:API. Auto-increment integers serialized as ints break strict clients. Cast in the resource, or use UUIDs — and if you use UUIDs, confirm the generated migration and route-model binding actually use them, since the stubs assume increments.

Sparse fieldsets and includes. Check whether the generated controller honors ?fields[posts]=title and ?include=. If not, included will be absent and clients will fall back to extra requests. Eager-load only what the relationship spec declares, and guard against unbounded include recursion on self-referential relations.

Pagination shape. The spec uses page[number]/page[size] and links objects; Laravel's paginator defaults to ?page=. Confirm the resource wraps the paginator correctly, otherwise every list endpoint silently violates the contract.

Relationship endpoints. /posts/{id}/relationships/{relation} (GET/POST/PATCH/DELETE) is frequently missing from generators of this vintage. Check the generated route list with php artisan route:list --path=api and add them manually if absent.

Debugging loop: route:list for what was actually registered, the generated test for the expected payload, and Storage::/log dumps in the resource for what was actually serialized. If output looks flat, you edited the model instead of the resource.

Extension points worth using: publish and edit the stubs (cheapest customization), set the generator's namespace/path config to isolate output under App\Api\, and extend the generator's base classes only if you need repeatable custom output. Given the maintenance status, keeping your customizations in stubs and config — rather than patches to vendor/ — is the only thing that survives a composer update.