Jsonrpc Http Server Swagger Doc Sdk Laravel Package

Technical Evaluation

Architecture fit. This is a documentation generator, not a server. Its only correct placement is build/CI time — it reflects over JSON-RPC method definitions and emits a machine-readable spec. That framing determines everything else: the package sits outside the request path, outside runtime concerns, and outside anything Laravel's service container would normally manage.

Fit is strictly conditional on already having committed to the yoanm/jsonrpc-server-sdk family as the source of truth for method definitions. Without that upstream dependency, this package has no input to work from and no value. Laravel itself is REST-shaped — routing, middleware, form requests, API resources, and route:list all assume resourceful endpoints — whereas JSON-RPC collapses everything into a single POST endpoint dispatching on a method field. That's a deliberate architectural trade (strongly-typed method contracts, batching, transport-agnostic clients) that a team should already have made for other reasons. This package is a consequence of that decision, not a justification for it.

Integration feasibility. Low difficulty, high ownership cost. It's framework-agnostic plain PHP installed via Composer, so the integration is roughly: instantiate the generator against the server SDK instance, call a render/serialize method, write JSON (or YAML) to public/ or a storage path, and serve it statically or publish it as a CI artifact. Expect ~50–100 lines of glue wrapped in an Artisan command. There is no service provider, no publishable config, no facade — normal for a framework-agnostic library, but it means nothing is covered by upstream tests at the Laravel seam. You own that glue permanently.

Technical risk.

• Swagger 2.0 as the output target is the material risk. OpenAPI 3.x is where ecosystem investment has gone for years; 2.0 is legacy-but-supported. Swagger UI still renders it and Postman/Insomnia still import it, but any consumer tooling built for 3.x in the last several years will reject the output. Budget for a swagger2openapi conversion step or accept a degraded consumer experience.
• Adoption signal is effectively zero. 0 stars, 0 dependents, no community bug corpus, no third-party usage to look at. This is not proof of poor quality — the maintainer's JSON-RPC family is coherent and the recent 2025-09-03 release shows active stewardship — but it does mean you are the QA function. Every edge case in param schema generation is one you discover first.
• Single-maintainer ecosystem. Bus factor of one across the whole JSON-RPC stack (server SDK, HTTP server SDK, this doc SDK). If maintenance lapses, replacing this generator is easy; replacing the server SDK underneath it is not.
• Dependency constraint collisions. Expect transitive Symfony constraints. Laravel 11/12 pin Symfony 7.x; older releases pin 6.x. An incompatible constraint range turns a "simple Composer require" into a fork-and-patch exercise.

Key questions.

1. Does the output include a complete definitions graph with $ref reuse, or does it inline/duplicate object schemas?
2. Are security schemes (bearer, API key) expressible, or is auth undocumented?
3. Can it emit both JSON and YAML, and is the output deterministic/stable across runs (for diff-able commits)?
4. What PHP versions and yoanm/jsonrpc-server-sdk constraint ranges are supported, and does that resolve cleanly against our Laravel/Symfony pin?
5. Does it support any OpenAPI 3.x emission path, or is 2.0 hardcoded?
6. How does it handle complex/nested parameter types, union-ish "one of many" params, and examples?

Integration Approach

Stack fit. Composer + PHP 8.x, no Laravel coupling — technically compatible. Verify the Symfony component constraints against the app's Laravel version before writing any code; a resolution failure is the single most likely reason this spike dies in an hour. Keep the package in require-dev if the generator is only invoked from CI or an admin-only Artisan command, which keeps it out of production dependency resolution.

Migration path. Additive, not a migration. There is no existing artifact this replaces unless the team maintains a hand-written API doc for the RPC surface — in which case, retire that document only after the generated output is verified equivalent, and keep it in git history as the reference. If a REST API exists alongside the JSON-RPC surface, expect two documentation pipelines; do not attempt to merge them into one spec.

Compatibility. Generated 2.0 documents are consumable by Swagger UI, Postman, Insomnia, and swagger-cli validate. They are not consumable by OpenAPI-3-only generators (most modern SDK generators). If downstream client SDK generation is a requirement, add a conversion step and validate the converted output, not the source.

Sequencing.

1. Confirm the premise. Verify a JSON-RPC server built on the yoanm SDK exists or is genuinely funded. If not, stop here — nothing downstream matters.
2. Two-hour spike. Stand up a two-method server, generate the spec, inspect the raw output for $ref quality, security schemes, and param coverage. This single step resolves most of the risk above.
3. Constraint check. Resolve against the target Laravel version in a throwaway branch.
4. Wrap it. Artisan command behind a narrow interface (SpecGenerator::generate(): array). No package classes referenced outside that wrapper.
5. CI integration. Generate on every merge to main, validate the schema, fail the build on drift. Commit the artifact or publish it — but make it a build output, never a hand-edited file.
6. Decide on 3.x. If any consumer needs OpenAPI 3, add conversion here and treat the 2.0 output as an intermediate.

Operational Impact

Maintenance. Small dependency footprint, MIT license, recent release cadence. Cost is not in upgrades — it's in the glue and in owning the correctness of generated output. Pin an exact version; a 0.x-style package can change rendering behavior in a patch. Monitor the maintainer's release activity quarterly; a 12-month gap on a single-maintainer package should trigger the exit evaluation.

Support. None commercial. Self-support means the wrapper interface is your real insurance policy: if the package breaks or is abandoned, you reimplement generate() behind the same interface and nothing else in the codebase moves. This is the mitigation that makes the low adoption signal tolerable.

Scaling. Not a runtime concern. Generation is O(methods) and runs in CI seconds. The scaling question is organizational: as the method count grows into the hundreds, spec size and diff noise grow with it — a large generated JSON blob committed to git becomes an unreadable review artifact. At that point move to artifact publication rather than commits.

Failure modes.

• Silent doc drift — the dominant risk. If generation isn't wired into CI with a fail-on-change check, the spec becomes stale within weeks, and stale API docs are worse than none because consumers trust them. This is a process failure, not a package failure, and it is the one most likely to actually occur.
• Generation exceptions on edge-case param types — surfaces as a broken build, not broken production. Acceptable blast radius.
• Dependency resolution break on a Laravel upgrade — build-time only; blocks the upgrade branch until patched or forked.
• Consumer rejection of Swagger 2.0 by modern tooling — discovered late, typically when a partner tries to generate a client. Mitigate by validating with an actual downstream consumer during the spike, not just with Swagger UI.
• Zero runtime failure modes, which is genuinely the package's strongest property: nothing here can page anyone at 3am.

Ramp-up. A mid-level PHP developer is productive in under a day — the API surface is small and the concept (describe a method's params, emit a spec) is obvious. The real ramp-up is domain literacy in JSON-RPC itself and in the upstream server SDK's method-definition model; allocate the learning budget there, not to this package. Expect the first iteration to produce a spec that's structurally valid but semantically thin (no examples, no security schemes) unless someone explicitly drives those concerns.

Recommendation. Adopt conditionally, as a build-time-only dependency behind a wrapper interface, gated on the spike confirming output quality and Composer resolution. The opportunity score and 0.4 quality signal are not disqualifying for a generator with zero runtime surface — but they do mean this should never become load-bearing infrastructure without an exit path.