Openapi Laravel Package

Technical Evaluation

Architecture fit. psx/openapi is a framework-agnostic set of PHP model classes that let you construct an OpenAPI document programmatically (type-safe builders rather than YAML/annotations). That makes it installable in a Laravel app with zero ceremony — no service provider, no facade, no config publishing. The catch is that it has no awareness of Laravel's routing, controllers, form requests, or resources. It is not a code-first generator like dedoc/scramble and not an attribute-driven annotator like zircote/swagger-php. Adopting it means you hand-author the spec alongside your application code, which creates a second source of truth and a structural drift risk between the OpenAPI document and the live API surface.

Integration feasibility. Composer-installable, Apache-2.0, PSR-4 autoloading. Realistically it lives inside one or two classes: an OpenApiBuilder service that assembles the spec, and an php artisan openapi:generate command that writes openapi.json for CI or a docs portal. That is a small, contained integration. The friction is in the PSX object model itself — you must learn its class taxonomy (Spec, Info, Path, Operation, Schema, etc.) and its conventions, and public documentation for this specific package is thin.

Technical risk. High, driven almost entirely by project health:

• 2 stars, 0 dependents, single maintainer (apioo / Christoph Kappestein). This is essentially a personal-ecosystem package.
• It is one node in a broader PSX stack (psx/api, psx/schema, psx/data); the value proposition is stronger if you adopt the whole stack, which is a poor fit for a Laravel codebase.
• Release cadence and PHP/Laravel version support are unverified; a package pinned to older PHP constraints can block framework upgrades.
• Generation-only by design — it does not parse, validate, or serve specs, so you still need cebe/php-openapi or similar for validation and stoplight/spectral for linting.

Key questions before commitment.

1. Which OpenAPI versions are modeled — 3.0 only, or 3.1 (JSON Schema 2020-12 alignment)?
2. What PHP constraint does the current release declare, and does it intersect with our Laravel/PHP matrix?
3. Is the package actively maintained (commit and release recency), and what is the bus factor mitigation?
4. Does it serialize cleanly to JSON/YAML without pulling in the rest of the PSX runtime?
5. What is our intended direction — spec-first contract, or code-first derivation? If code-first, this is the wrong tool.

Verdict. Technically viable, strategically weak. Score 0.01 and a 44.34 opportunity rating reads as "interesting primitive, no ecosystem." Recommend a time-boxed spike only, and only if we specifically want a programmatic, non-annotation spec builder.

Integration Approach

Stack fit. Laravel 10/11 + PHP 8.x. Install via Composer, wrap in a single App\OpenApi\SpecBuilder service registered in the container, and expose an artisan command that emits the artifact. Keep the PSX classes behind an internal interface (SpecEmitter) so the dependency is swappable — this is the single most important design decision given the project-health risk. No middleware, no runtime request-path involvement; this belongs at build/CI time, not in the request lifecycle.

Migration path. Treat it as an incremental, endpoint-by-endpoint migration, not a big bang:

1. Spike (2–3 days): build a spec for 2–3 representative endpoints, including a resource with nested schemas, auth security schemes, and error envelopes. Confirm output validates against OpenAPI 3.x with Spectral.
2. Comparison gate: implement the same 3 endpoints with zircote/swagger-php and dedoc/scramble. If Scramble can derive ~80% of the spec from existing Laravel constructs, the manual builder loses on economics — fewer lines to maintain and no drift.
3. Pilot: if the builder wins (e.g., because we need deterministic, reviewable, hand-curated contracts), migrate one bounded module.
4. CI wiring: emit openapi.json on every build, diff against the committed artifact, fail on unexpected changes; lint with Spectral; add contract tests (Dredd/Schemathesis) against a running app so the spec is provably accurate.
5. Broaden module by module; retire any legacy annotation-based generation last.

Compatibility. Verify PSR-4 autoload conflicts and transitive psx/* dependencies before merging. Watch for PHP constraint ceilings during framework upgrades — pin the version and record an upgrade-escape plan (fork under our org namespace if abandoned). Apache-2.0 permits forking and internal vendoring, which is the primary mitigation.

Sequencing. Decision gate first (build vs. Scramble vs. swagger-php), then abstraction layer, then pilot, then CI enforcement, then rollout. Do not wire CI enforcement before the abstraction layer exists.

Operational Impact

Maintenance. Low ongoing code churn — a spec builder is largely declarative — but high dependency-health overhead. Expect to own the upgrade path ourselves. Budget for periodic audits (PHP version bumps, OpenAPI version bumps) and maintain a fork-ready posture: vendor the package or mirror it if upstream goes quiet.

Support. Effectively none. No Stack Overflow footprint, no community, single maintainer, thin docs. Onboarding and troubleshooting cost lands entirely on the adopting team. Contrast with swagger-php or scramble, where answers and examples are abundant.

Scaling. Negligible at runtime since generation is build-time. For very large APIs (hundreds of operations) PHP object graph construction can be memory- and time-heavy in CI; monitor build durations and consider chunked generation if the spec exceeds a few megabytes. Serving the resulting static JSON should be via CDN/static hosting, not through the Laravel app.

Failure modes.

• Spec drift — the dominant risk: routes change, builder isn't updated, docs lie. Mitigate with contract tests and CI diffs, not just review discipline.
• Silent abandonment — no releases for a PHP version we need; blocked upgrades.
• Serialization mismatches — emitted JSON subtly invalid against OpenAPI 3.x; only caught if Spectral lint is enforced.
• Ecosystem creep — pulling in psx/* transitives that conflict with or bloat the Laravel app.
• Single-maintainer key-person event — mitigated by Apache-2.0 fork rights.

Ramp-up. Expect 2–4 developer-days to become productive with the PSX object model versus roughly half a day for Scramble's code-first approach. That ramp-up cost is per-engineer and recurs with turnover, since the model is non-obvious and under-documented. Weigh it against the long-term maintenance savings of a curated contract; for most Laravel teams, it doesn't pencil out unless a hand-authored, reviewable specification is an explicit product requirement.