Jsonrpc Http Server Swagger Doc Sdk Laravel Package

Getting Started

This package sits at the very end of the yoanm JSON-RPC stack: it takes a description of your JSON-RPC methods and emits a Swagger 2.0 document for the HTTP transport. It does not serve the doc, render UI, or validate anything — it builds an array/object you serialize yourself. That narrow scope is the point, but it also means most of the day-to-day work is wiring it into your app's doc pipeline.

Minimal setup:

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

Install it as a dev dependency. Doc generation belongs in build/CI or a local-only route, not in the request path of every RPC call.

Where to look first

1. README.md — the usage block is usually the only public API contract.
2. src/ — find the main builder class and the Doc/Model classes. The builder is your entry point; everything else is data.
3. tests/ — for a package with zero stars and no dependents, the test fixtures are more reliable documentation than the README. They show the exact shape the builder expects.
4. composer.json — confirm which sibling packages it pins (yoanm/jsonrpc-server-sdk, the doc model package, PSR-7/HttpFoundation version). Version skew between the server SDK and the doc SDK is the most common source of "why is my schema empty".

First use case

Document one method and serve the result:

// Illustrative shape — confirm FQCNs against src/ and tests/
use Yoanm\JsonRpcHttpServerSwaggerDoc\SDK\SwaggerDocBuilder;

$doc = (new SwaggerDocBuilder())
    ->setInfo('Acme RPC', '1.0.0')
    ->setHost('api.example.test')   // host only, no scheme
    ->setBasePath('/rpc')
    ->addMethodDoc($pingMethodDoc)  // your method description object
    ->build();

file_put_contents(
    storage_path('app/rpc-swagger.json'),
    json_encode($doc->toArray(), JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES)
);

Then load that JSON into Swagger UI (CDN build is fine) and hit POST /rpc with {"jsonrpc":"2.0","method":"ping","id":1}. Getting one method end-to-end through UI is the fastest way to discover how the package models the JSON-RPC envelope, params, and errors — that model drives everything else.

Implementation Patterns

Keep the doc registry next to method registration. The failure mode with any doc generator is drift. Register method docs in the same place you register the method itself — a service provider, a MethodRegistry class, or a config array — so adding a method without a doc is visible in review.

// app/JsonRpc/Registry.php
public function methods(): array
{
    return [
        'user.get'  => new GetUserMethod(),
        'user.list' => new ListUsersMethod(),
    ];
}

public function methodDocs(): array
{
    return [
        'user.get'  => $this->docForGetUser(),
        'user.list' => $this->docForListUsers(),
    ];
}

Build in a command, serve a static file. For Laravel this is the cleanest split:

• php artisan rpc:docs builds the Swagger JSON and writes it to public/rpc/swagger.json (or storage/app/... served by a controller).
• A route serves the cached file; it never invokes the builder.
• CI runs the command and fails if the file differs from the committed one — a cheap contract test.

class GenerateRpcDocs extends Command
{
    protected $signature = 'rpc:docs';

    public function handle(SwaggerDocBuilder $builder)
    {
        $doc = $builder->build();
        File::put(public_path('rpc/swagger.json'), $doc->toJson());
    }
}

Resolve the builder through the container so info/host/basePath come from config, not from call sites. A singleton binding with config('app.url') parsed into host and a configured basePath keeps environments consistent.

Derive schemas from the same source as validation where possible. If your param validators already encode types and required flags, map them into the doc model programmatically rather than hand-writing JSON Schema. Hand-written docs are the ones that go stale.

Pair with Swagger UI, but expect caveats. A CDN swagger-ui-dist pointing at /rpc/swagger.json is enough for internal docs. For ReDoc or Stoplight, the same JSON works. For client generation, treat it as reference only — Swagger 2.0 + JSON-RPC semantics do not round-trip cleanly into REST clients.

Version the doc with the API. info.version should be bumped alongside method changes. If you support multiple API versions, build one doc per version and serve at /rpc/v1/swagger.json, /rpc/v2/swagger.json.

Gotchas and Tips

• Swagger 2.0 is the hard constraint. No oneOf/anyOf, no nullable. A JSON-RPC method whose params are a union of shapes cannot be expressed precisely. Expect to loosen schemas or use x- vendor extensions.
• One endpoint, many methods. The package almost certainly models each RPC method as a pseudo-path (or a method enum on a single path). If it uses pseudo-paths, Swagger UI's "Try it out" will POST to the wrong URL. Either accept that Try-it-out is broken, or document a single path and lose per-method schema detail. Read the tests to see which choice was made before designing your UI.
• JSON-RPC envelope vs. params. Decide explicitly whether the schema describes the full envelope (jsonrpc, id, method, params) or just params. Mixing the two across methods produces a doc that no one can use.
• Errors are HTTP 200. JSON-RPC error responses are 200 OK with an error member. Swagger's status-code-centric response model is misleading here. Document the success and error shapes as a loose union on 200 and add x- annotations for the error codes.
• Batch requests and notifications (no id, 204 No Content) have no good Swagger 2.0 representation. Mention them in the description field and move on.
• host must be hostname only; basePath must start with /. Mixing scheme into host silently produces broken generated URLs.
• Deterministic output matters. Sort methods and keys before writing, so CI snapshot diffs are meaningful. Otherwise every build shows churn.
• Cache aggressively, build rarely. The builder introspects method metadata; don't call it per request. A stale doc in dev is a rpc:docs run away.
• Guard the route. In production either don't expose it, or protect it with auth — internal method names and parameter shapes are useful reconnaissance.
• Pin the version and read the source. Zero stars and zero dependents means no community safety net. The package was released recently (2025-09-03), so the API is still settling. Lock the exact version in composer.json and keep a smoke test that builds a doc and asserts a known method appears.
• Extension point: if the generated doc is structurally wrong for your needs, the builder's build() output is just an array — post-process it (add securityDefinitions, inject x- metadata, rewrite paths) before serializing rather than forking the package.