Jsonrpc Http Server Openapi Doc Sdk Laravel Package

Getting Started

This package generates an OpenAPI 3.0.0 document from a JSON-RPC server definition built with yoanm/jsonrpc-server-sdk. It exists because JSON-RPC over HTTP collapses to a single POST / endpoint with a polymorphic body — without generated docs, consumers have nothing to code against. The SDK reads each registered method's name, description, params schema and result schema, and emits a spec you can drop into Swagger UI / Redoc / Stoplight.

Minimal steps:

composer require yoanm/jsonrpc-http-server-openapi-doc-sdk --dev

It is a documentation-time concern, so default to --dev unless you serve the spec at runtime (see below). It pairs with yoanm/jsonrpc-http-server-sdk and yoanm/jsonrpc-server-sdk — install those at the versions you already use.

Where to look first:

1. The README (short) for the top-level doc class name.
2. src/ — the package is small; the generator is a thin traversal over the server's method collection, so reading the source is faster than guessing.
3. Your existing JsonRpcServer bootstrap — that object is the only input you need.

First use case — a build-time script that dumps public/openapi.json:

// bin/generate-openapi.php  (adjust FQCNs to the versions you installed)
$server = require __DIR__.'/../config/jsonrpc-server.php'; // returns your JsonRpcServer

$doc = new JsonRpcHttpServerOpenApiDoc($server);

file_put_contents(
    __DIR__.'/../public/openapi.json',
    json_encode($doc->toArray(), JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES)
);

If your server is wired inside a framework container, resolve it from the container in a console command (php artisan openapi:generate, bin/console app:openapi) rather than rebuilding method definitions in a second place.

Implementation Patterns

Single source of truth. The whole value of this package is that the doc is derived from the same method registry the HTTP middleware uses. Never hand-maintain openapi.json. Factor the server construction into one factory (config/jsonrpc-server.php returning the configured JsonRpcServer) and consume it from both the PSR-15 middleware and the doc generator.

Annotate methods, not the generator. Push descriptive data down into the method definitions — description, param schema, result schema. The generator is a mechanical mapper; anything it can't see in the method it can't put in the spec. Treat "does this show up correctly in Swagger UI?" as a code-review question on method registration.

Build-time generation with a CI diff. Commit the generated openapi.json and fail the build if regeneration produces a diff. That gives you free review of API contract changes in pull requests — the diff is the changelog for consumers. Run a linter (Spectral, openapi-generator validate) as a second CI step, since the SDK will happily emit structurally-invalid-adjacent schemas.

One document per endpoint, shared methods. If you expose a public and an admin JSON-RPC endpoint, build two server instances with different method sets and generate two specs. Don't try to squeeze both into one document with tags — JSON-RPC clients need to know which URL to POST to.

$publicServer = $factory->public();
$adminServer  = $factory->admin();

foreach (['public' => $publicServer, 'admin' => $adminServer] as $name => $server) {
    file_put_contents(
        "public/openapi-{$name}.json",
        json_encode((new JsonRpcHttpServerOpenApiDoc($server))->toArray(), JSON_PRETTY_PRINT)
    );
}

Runtime serving. If you prefer not to write a file, add a PSR-15 route that serialises the array on demand, with a long Cache-Control and an ETag derived from a hash of the output. Gate it behind APP_DEBUG or an internal-only route — the spec enumerates every method you expose, including admin ones if you're careless.

Post-processing for the parts it can't infer. Server URLs, contact/legal info, securitySchemes and global security are deployment concerns the package cannot know. Merge them in after generation, either with array_replace_recursive or by wrapping the generator in your own decorator class. Keep that customisation in your repo, not in a fork.

Gotchas and Tips

• One path, one operation — that's correct. Your spec will show POST / with a single operation. Reviewers often read this as a bug. It isn't; it's what JSON-RPC over HTTP looks like. Add a long operation description explaining the envelope (jsonrpc, method, params, id) because OpenAPI has no native way to express it.
• "Try it out" is clumsy. Swagger UI will pre-fill a body from your request schema, but callers must hand-write the JSON-RPC envelope. Document a copy-paste example in the operation description; consider adding examples to the request body to make it tolerable.
• OpenAPI 3.0.0 dialect, not JSON Schema 2020-12. Use nullable: true, not type: ["string","null"]. No $defs, no const. If your param schemas come from a newer JSON Schema source, expect to normalise them before generation.
• Version-pin the trio. This package reads the server SDK's domain objects; a major bump in yoanm/jsonrpc-server-sdk can break doc generation before it breaks the runtime. Pin jsonrpc-server-sdk, jsonrpc-http-server-sdk and this package together and upgrade as a unit.
• Debug by dumping the array. When a method is missing or a schema is empty, var_export($doc->toArray()) and diff against expectations. json_encode failures are almost always invalid UTF-8 in a description, not an SDK bug.
• Snapshot-test the output. With one maintainer and effectively zero dependents, upstream regressions are plausible and support is best-effort. A assertJsonStringEqualsJsonFile test over the generated spec turns an upstream surprise into a red test rather than a broken client.
• Extension points are shallow. The practical customisation surface is: decorate the generator, or post-process the array. Don't subclass internals — they're not a public API in any meaningful sense.
• MIT licenced, released Sept 2025. Fine to vendor or fork if you need a fix; the codebase is small enough to maintain a patch on top of.