Jsonrpc Http Server Openapi Doc Sdk Laravel Package

Technical Evaluation

Architecture fit. This is a documentation-generation SDK, not a runtime framework component. It sits at the edge of the yoanm PHP JSON-RPC ecosystem (php-jsonrpc-common → php-jsonrpc-http-server → this doc SDK) and emits an OpenAPI v3.0.0 document describing a JSON-RPC-over-HTTP server. Its value to a Laravel product is therefore conditional: it only pays off if we have deliberately chosen JSON-RPC as our API transport. Laravel's idiomatic surface is REST/GraphQL; JSON-RPC is a narrow fit for internal service-to-service calls, batch operation, or exposing a single POST endpoint with method dispatch. If that is the target, the SDK is a plausible fit. If not, it is a solution looking for a problem.

Integration feasibility. Framework-agnostic PHP with a likely Symfony-leaning dependency graph (serializer, YAML, JSON-schema validation). There is no Laravel service provider, no config publishing, no artisan command. The realistic pattern is: register the JSON-RPC server and method map in a Laravel service provider, expose one route in routes/api.php, and invoke the doc generator from a custom artisan command or a CI step that writes openapi.json into the build artifacts. That is a modest amount of glue code — a day or two of spike work — but it is glue we own forever. Also note that OpenAPI is resource-oriented; a single RPC endpoint with method dispatch tends to produce a spec whose paths and operations read awkwardly for external consumers and for tooling like Swagger UI, Postman import, or SDK generators.

Technical risk. High, relative to the value delivered. Signals: 1 star, 0 dependents, a single-maintainer project, score 0.305. Recent release activity (2025-09-03) is the one genuinely positive indicator — the package is not abandoned — but recency without adoption means the code has not been battle-tested by third parties. Additional risks: version-coupling to the yoanm common/server packages means an upgrade in one forces upgrades across the trio; the emitted spec is only as accurate as our method metadata, so drift between code and docs is a live failure mode; and PHP/Symfony version constraints must be verified against our Laravel version's dependency set before we commit (composer conflicts are the most likely blocker).

Key questions.

1. Is JSON-RPC a committed architectural decision, or a hypothetical? If hypothetical, stop here.
2. Who consumes the generated OpenAPI — external partners, internal frontend, or just our own tooling? External consumers raise the readability concern.
3. Does the generator cover our method surface (params, schemas, errors, batch semantics), or will we be patching it?
4. Is the maintainer responsive? Has anyone filed or resolved issues? Worth a test PR before adoption.
5. What is the fallback? A hand-maintained openapi.yaml, or Laravel-native tooling (Scramble, Scribe, dedoc/knuckles), which we would likely use if the transport were REST.
6. Does doc generation run in CI (fail the build on drift) or manually (rot guaranteed)?

Integration Approach

Stack fit. Moderate-to-poor for a standard Laravel stack, good only for the narrow JSON-RPC case. Expect to bypass Laravel's routing, middleware, validation, and resource layers and hand requests to the yoanm server (PSR-7/PSR-15 style). That means our Laravel auth, throttling, and observability middleware either wrap the RPC route at the HTTP layer or must be reimplemented inside RPC method handlers. Budget for that duplication explicitly — it is the most commonly underestimated cost in this kind of integration.

Migration path. There is no incremental migration from an existing REST API; JSON-RPC is a different contract shape. The realistic path is greenfield: a new internal endpoint area (/api/rpc) alongside existing REST routes, sharing auth and the domain/service layer underneath. Do not attempt to express existing REST resources as RPC methods; that produces a worse API than either alternative. If the JSON-RPC surface already exists and we are only adding docs, the migration is trivial — install, wire a command, generate.

Compatibility. Two gates to clear in the spike, both cheap to test and both potentially fatal:

• Composer resolution against our PHP and Laravel versions (Symfony component constraints are the usual culprit).
• OpenAPI 3.0.0 output validity — run the generated doc through a validator and a Swagger UI render before trusting it. 3.0.0 rather than 3.1 means some newer tooling will be mildly annoyed but nothing should break.

Sequencing. (1) Spike: install in a scratch branch, generate a spec from two or three representative methods, validate and render it. Gate on output quality. (2) Decide: adopt / hand-roll / abandon. (3) If adopt, add an artisan command plus a CI job that regenerates and diffs the spec, failing on drift. (4) Then, and only then, expose the RPC surface to consumers. Keep the doc generation step isolated behind an interface so it can be swapped for a hand-written spec without touching runtime code.

Operational Impact

Maintenance. Low ongoing code cost, non-trivial ongoing ownership cost. The generator itself needs little care; the method metadata that feeds it needs the same discipline as any schema — every new RPC method must carry accurate parameter and result definitions or the docs silently lie. That is a process obligation, not a library one. We also inherit the yoanm version chain, so a PHP upgrade may require coordinated bumps across three packages we do not control.

Support. Effectively none. One star and zero dependents means no community, no Stack Overflow corpus, no third-party blog posts, and no peer to ask. The maintainer may be excellent, but we cannot assume responsiveness, and we cannot hire for this. Treat the package as "code we have read and are prepared to fork." If a security or compatibility issue lands, we patch it ourselves. MIT license makes forking legally clean, which is the main mitigation.

Scaling. Doc generation is a build-time/on-demand operation with negligible runtime footprint — it does not sit in the request path and will not affect throughput. The JSON-RPC server it documents is the scaling consideration, not this SDK. One caveat: if we regenerate docs on every deploy, keep the step off the critical path of the deploy so a generator failure cannot block a release.

Failure modes.

• Silent drift: spec diverges from implementation because metadata was not updated. Mitigation: CI diff on the generated artifact.
• Composer conflict on a framework or PHP upgrade, blocking unrelated work. Mitigation: pin and isolate; keep the doc step in a separate composer group or CI image.
• Generator crash on an exotic method signature, taking the docs pipeline down. Mitigation: non-blocking CI step with alerting, not a hard deploy gate — at least initially.
• Abandonment: repo goes quiet, we are stranded on an old version. Mitigation: fork-and-vendor readiness, plus the escape hatch of a hand-maintained spec.
• Consumer confusion: partners misread the RPC-over-OpenAPI mapping. Mitigation: review rendered docs with an actual consumer before publishing.

Ramp-up. Shallow for anyone who already knows JSON-RPC and OpenAPI; the package API surface is small. Budget half a day of reading plus the spike. The real learning curve is the surrounding yoanm server stack (request handling, middleware, error mapping), which is where a Laravel developer's instincts will mislead them. One engineer can own this end to end.

Recommendation. Conditional no-go by default. The adoption signal (1 star, 0 dependents, score 0.305) is too weak to justify making this a dependency of anything customer-facing, and the OpenAPI-over-JSON-RPC impedance mismatch limits the payoff even when it works. Fund a one-to-two-day spike only if JSON-RPC is already a decided architectural direction; if the spike shows clean spec output against our real method surface, adopt with a CI drift check and a fork-ready posture. If JSON-RPC is still under debate, spend the same effort on Laravel-native OpenAPI tooling instead — it will produce a better spec, with a larger support community, for a resource-oriented API that better matches the framework and the team.