Symfony Jsonrpc Http Server Openapi Doc Laravel Package

Technical Evaluation

Architecture fit — the framing problem first. This is a Symfony bundle, not a Laravel package. It ships no ServiceProvider, no publishable config, no Laravel route registration, and no facade. It is also not a JSON-RPC server: it is a documentation adapter that projects an existing yoanm/symfony-jsonrpc-http-server method catalog into an OpenAPI 3.0.0 spec. Its value is entirely contingent on adopting the surrounding yoanm stack — the server bundle, the jsonrpc-doc generators, and their method-registration conventions. For a Laravel codebase, the honest reading is: this package is reference material and a spec-generation pattern, not a drop-in dependency.

• What it actually does well: JSON-RPC APIs are notoriously under-documented. Auto-deriving an OpenAPI 3.0.0 document from the same method definitions that drive dispatch eliminates spec drift — the single highest-value property in API documentation. That is a real, defensible outcome.
• What it does not do: it does not give you a Laravel-native route, middleware, auth, or config surface. It assumes Symfony's DI container, bundle extension (Configuration/Extension classes), and routing loader.
• Coupling: tight and bidirectional. The doc layer reads the server bundle's method registry. You cannot adopt the docs without the server, and you cannot remove the server later without rewriting the docs.
• Protocol mismatch to flag upward: OpenAPI is resource/REST-shaped; JSON-RPC is single-endpoint method dispatch. Any OpenAPI projection of JSON-RPC is a lossy model (typically one POST / with a oneOf request body keyed by method). It will confuse consumers, codegen tools, and API gateways that expect REST semantics. Do not let stakeholders believe "we have OpenAPI" means "we have REST-grade tooling."

Integration feasibility — two paths, one of which uses this package.

Technical risk (scored for a decision memo):

• Adoption risk — High. 1 star, 0 dependents, internal score 0.495. There is essentially zero third-party validation: no downstream projects to observe, no community troubleshooting corpus. Any defect becomes a maintainer conversation or a fork.
• Bus factor — High. Single-maintainer ecosystem. Mitigated only by MIT license (forkable) and a recent release (2025-09-16), which is a genuine positive maintenance signal — someone is shipping.
• Framework mismatch — High (Path A), Medium (Path B). Laravel bundles several Symfony components, so technically a bundle can be booted inside a Laravel service provider, but this is an unsupported, undocumented pattern with sharp edges around container bridging and route loading. Budget for it or avoid it.
• Lock-in — Medium-High. Method naming, schema derivation, and error-shape conventions become load-bearing. Exit means rewriting server and docs.
• Version-surface risk — Medium. Bundle constraints on Symfony 5/6/7 and PHP 8.x must be reconciled with your actual runtime; a mismatch can force a PHP upgrade as a hidden cost.

Key questions to resolve before any commitment:

1. What are the exact composer.json constraints — Symfony and PHP versions — and do they intersect with our runtime?
2. Does the doc bundle require the yoanm server bundle at runtime, or can it consume a method catalog at build time only? (A build-time-only mode would materially change the calculus.)
3. How are method schemas declared — PHP 8 attributes, YAML config, or annotations? This determines authoring ergonomics and how much ceremony each new method costs.
4. Is the spec generated per-request or as a cached artifact? What is the generation cost per endpoint?
5. OpenAPI 3.0.0 only, or is 3.1 supported? 3.1 matters if we need JSON Schema 2020-12 alignment.
6. Can the documentation route be disabled or auth-gated in production without forking?
7. What is the test coverage and CI posture of the bundle itself — does it have a green matrix across supported versions?
8. Is the maintainer responsive on issues, and what is the observed release cadence over the last 24 months?

Integration Approach

Stack fit. The package is a native fit for: Symfony 5.4/6.x/7.x + PHP 8.1+ + yoanm/symfony-jsonrpc-http-server. It is a non-fit for Laravel as a direct dependency. Treat "Laravel compatibility" as not supported, and plan accordingly — the asymmetry is the central fact of this assessment.

Migration path (recommended: Path B, borrowing the design).

1. Spike (3–5 days, timeboxed). Stand up a throwaway Symfony app with the yoanm server + this bundle. Publish one method. Confirm the generated spec shape, the method-declaration ergonomics, and the OpenAPI version emitted. This is cheap and answers questions 1–6 empirically rather than by inference.
2. Decide the protocol question. Before writing code, confirm that a single-endpoint, oneOf-dispatched OpenAPI document is acceptable to consumers. If the real requirement is REST-grade tooling (SDK codegen, gateway policies, Mockoon/Postman collections), JSON-RPC-over-OpenAPI will not deliver it and the project should be reframed.
3. Port the pattern, not the package. Pull the framework-agnostic jsonrpc-doc generation libraries; wrap them in a Laravel ServiceProvider + artisan command that emits openapi.json as a build artifact, not a runtime endpoint. Serve it read-only from public/ or a CDN.
4. Wire into CI as a drift gate. Regenerate on every merge; fail the build if the committed spec differs from generated output. This is the operational payoff — it converts documentation from a stale wiki into a tested contract.
5. Defer Path A entirely unless a separate Symfony service is independently justified. Do not stand up a microservice for documentation.

Compatibility notes. Pin the underlying doc libraries explicitly and record the OpenAPI version they emit. If the libraries' constraints drift away from your Laravel-supported PHP version, you will be pinned to an older library — plan an owner for that pin.

Sequencing. Spike → protocol/consumer sign-off → build-time generator in Laravel → CI drift gate → auth/exposure review of any served spec → only then consider serving live docs. Do not reverse this order; the exposure review is frequently skipped and frequently regretted.

Operational Impact

Maintenance. Two distinct burdens. (1) Dependency maintenance: you inherit the release cadence of a single-maintainer ecosystem with zero dependents. Expect to read source, not Stack Overflow, when something breaks. (2) Fork maintenance: if the maintainer goes quiet and a Symfony/PHP bump breaks it, you own the patch. MIT licensing makes this legal; it does not make it free. Budget a named owner and roughly 1–2 days per quarter of dependency hygiene, spiking during major PHP or Symfony upgrades.

Support. No vendor, no SLA, no community. Internal support means one engineer who has read the generator code. That is a bus-factor of one inside your own org, layered on top of the upstream bus-factor of one. Document the generator's behavior in an ADR while the spike is fresh — this is the single highest-leverage artifact you can produce.

Scaling. Generation cost is the only scaling axis and it is trivially bounded: the spec is a function of the method catalog, so generation is O(methods) and belongs at build time. Do not generate per-request — it adds latency and a failure mode for zero benefit. The spec document itself can grow large with many methods (discriminated unions balloon fast); plan pagination-by-tag or per-domain spec splitting past ~50 methods, and watch client-side renderer performance in Swagger UI/Redoc.

Failure modes to design against:

• Silent spec drift — the killer. Docs served at runtime that nobody regenerates. Mitigation: CI diff gate, non-negotiable.
• Build breakage from upstream — a transitive constraint bump fails composer update. Mitigation: committed composer.lock, dependabot with a human gate, not auto-merge.
• Information disclosure — a docs route exposing internal method names, parameter schemas, or error taxonomy in production. Mitigation: build-artifact-only serving, or explicit middleware auth; never rely on the bundle's defaults.
• Consumer misinterpretation — a partner's codegen produces a REST client that cannot speak JSON-RPC. Mitigation: ship a short "how to call this" README alongside the spec; the OpenAPI document alone is not sufficient onboarding.
• Protocol-coupling trap — the docs are correct only because they share the server's registry; the moment someone hand-edits the YAML, the guarantee evaporates. Mitigation: make the generated file read-only and reject manual PRs to it.

Ramp-up. For an engineer already fluent in Laravel: half a day to understand the pattern, 2–3 days for the Path B generator, and roughly a week before they can confidently extend method schemas. For Path A, add 1–2 weeks of Symfony bundle/DI literacy that has no reuse value in a Laravel org — a real cost with a poor return.

Bottom line for the portfolio. Do not add yoanm/symfony-jsonrpc-http-server-openapi-doc as a dependency in a Laravel codebase; the framework mismatch plus 1-star/0-dependent adoption makes the integration cost exceed the benefit. Do run the 3–5 day spike and mine it for the pattern — build-time spec generation from a single method registry, gated in CI. That pattern is worth 2–4 weeks of Path B work if you genuinely own a JSON-RPC surface. If you do not own a JSON-RPC surface, or if consumers need REST-grade tooling, close this out now and spend the budget on l5-swagger or scribe instead.