Jsonrpc Http Server Openapi Doc Sdk Laravel Package

Product Decisions This Supports

• Contract-first API documentation. The package generates an OpenAPI v3.0.0 document from HTTP JSON-RPC server method definitions. That makes the code the source of truth for the API contract, instead of a hand-maintained YAML/JSON file that drifts the moment a param changes.
• Build vs. buy for API docs. Hand-writing OpenAPI for every JSON-RPC method is tedious, error-prone, and the first thing to rot. If we're already defining methods as structured objects, the marginal cost of emitting a spec is one adapter — not a documentation project.
• Scoping what "done" means for an endpoint. Because the generator needs param and result schemas, it forces the team to declare types, required fields, and error shapes. Missing/loose schemas become visible as spec gaps — a useful forcing function for API design review before release.
• Unlocking downstream product surfaces. A real OpenAPI spec is the entry ticket for partner/developer portals (ReadMe, Redoc, Postman), gateway and mock-server configuration, generated client SDKs, and — increasingly — tool/function definitions for LLM agents. "We can publish an OpenAPI spec" is a roadmap enabler, not just a docs chore.
• Prioritizing the RPC surface. Deciding whether our JSON-RPC endpoints are a product (external developers, partners, monetized API) or purely internal plumbing changes whether this package is worth the dependency at all. Public/monetized → docs are non-negotiable; internal-only → skip.
• Ecosystem bet. This is part of the yoanm/php-jsonrpc-http-server family. Adopting it is really a decision to standardize on that JSON-RPC server stack, so it belongs in the same architecture review.

When to Consider This Package

Adopt-consider criteria:

• You are already using — or have decided to use — yoanm/php-jsonrpc-http-server with structured method definitions. The generator has no value outside that ecosystem; it is not a generic "scan my Laravel routes" tool.
• You must publish OpenAPI 3.0.0 specifically (partner requirements, API gateway, SDK generation, docs portal). If 3.1 / JSON Schema 2020-12 is required, this is the wrong tool.
• The team has no bandwidth to hand-author and maintain the spec, and the RPC method count is large enough that manual work is a real cost (roughly: more than a handful of methods, or changing frequently).
• You can absorb single-maintainer dependency risk: 1 star, 0 known dependents, one author. Mitigations are cheap here — pin the version, wrap it behind a thin internal interface (e.g., a SpecGenerator contract plus a Laravel artisan command), and be prepared to vendor or fork. The package's surface is small and its output is a file, so blast radius is low.
• Laravel integration is a half-day to two-day job, not a feature: no service provider, no config publishing, no facades. Plan for a custom console command plus a CI step that diffs the generated spec and fails on drift.

Look elsewhere when:

• The API is REST-first. Use dedoc/scramble, darkaonline/l5-swagger, or Scribe instead — they understand Laravel routing and are far better supported.
• You use a different Laravel JSON-RPC package (e.g., Sajya). This generator won't understand its conventions without a custom adapter, which erodes the buy-vs-build case.
• You need vendor SLAs, security-response commitments, or an actively maintained dependency — this has a very thin adoption signal and shouldn't sit on a compliance-sensitive path.
• You need rich examples, oneOf/discriminator fidelity, or 3.1 features.
• The RPC surface is internal-only and consumed by one service. Documentation value approaches zero; a README is enough.

Blunt read on the numbers: stars 1, dependents 0, score 0.305. That is not a red flag about quality so much as an absence of evidence. Treat it as an evaluation candidate for a spike, not a platform standard, until we've used it on one real service.

How to Pitch It (Stakeholders)

For executives (30 seconds): We can publish a machine-readable API contract for our JSON-RPC endpoints automatically, for zero license cost (MIT), by wiring a small adapter into our build. That unlocks partner onboarding, generated client SDKs, API gateway config, and AI tool definitions — things we currently can't offer without hand-writing specs we'd struggle to keep accurate. The risk is that it's a very small open-source project maintained by one person; we contain that by pinning the version, isolating it behind our own interface, and limiting it to one service initially. Cost to try: roughly 1–2 engineering days.

For engineering: This is a spec emitter, not a framework. It consumes yoanm/php-jsonrpc-http-server method definitions and outputs an OpenAPI 3.0.0 document. Integration surface is one artisan command plus a CI drift check — no runtime request-path involvement, no performance implications, no changes to how methods execute. Because it's a build-time tool, we can wrap it in an interface, pin the version, and swap or vendor it if maintenance lapses. It also has a nice side effect: it makes untyped params and undocumented error codes show up as gaps in the generated spec, which we can use as a lightweight API design checklist in review.

Recommendation: Run a one-sprint spike on a single internal service that already uses the yoanm stack. Success criteria: spec generates in CI, covers all methods, and is consumable by one downstream tool (docs portal, Postman, or SDK generator). If the spike lands, promote it to a standard for JSON-RPC services. If we don't standardize on the yoanm JSON-RPC server stack, don't adopt this — the dependency only pays off inside that ecosystem.