Symfony Jsonrpc Http Server Openapi Doc Laravel Package

Getting Started

This bundle sits on top of yoanm/symfony-jsonrpc-http-server; it does not replace it. You need a working JSON-RPC server (at least one registered method, reachable over an HTTP route) before the docs bundle has anything to describe.

1. Install and register. composer require yoanm/symfony-jsonrpc-http-server-openapi-doc. Because the package has no Flex recipe and essentially no adoption, expect to register the bundle manually in config/bundles.php (Yoanm\SymfonyJsonRpcHttpServerOpenApiDoc\... — confirm the FQCN from vendor/yoanm/symfony-jsonrpc-http-server-openapi-doc/src/).
2. Read these files first, in order: the package README.md, then src/DependencyInjection/Configuration.php (this is the authoritative schema for your YAML config — there is no reliable third-party documentation), then src/DependencyInjection/*Extension.php and src/Resources/config/services.yaml to see what services and routes get registered.
3. Look at the upstream library. This bundle is a thin wiring layer over yoanm/jsonrpc-server-openapi-doc (the spec-building logic lives there). When you need to understand how a method gets turned into an OpenAPI path/operation, drop into that package — it is where the real behaviour is.
4. First use case: boot the app, run bin/console debug:router | grep -i openapi, hit the generated docs route, and confirm you get a valid OpenAPI 3.0.0 JSON document listing your JSON-RPC methods. Then point Swagger UI or Redoc at that URL.

Implementation Patterns

Configure once, per environment. Typical shape is a bundle config block (verify key names against Configuration.php) that gives the OpenAPI info block (title, version) and the route/path where the spec is served. Keep the info.version in sync with something real (build number, git tag) rather than a hardcoded "1.0.0".

# config/packages/yoanm_jsonrpc_http_server_openapi_doc.yaml
yoanm_jsonrpc_http_server_openapi_doc:
    openapi:
        info:
            title: 'My JSON-RPC API'
            version: '%app.version%'
    # route/path options — check Configuration.php for exact keys

Describe methods at the source. Documentation quality is bounded by what your JSON-RPC method definitions expose: method name, description, parameter schema, return schema. In the yoanm ecosystem methods are usually declared as tagged services or via a method registry, and the doc builder reads that metadata. Invest in those descriptions — that is the whole payoff of the bundle.

Dump the spec at build time for production. Generating on every request is fine in dev but pointless in prod. A small console command (or a Makefile target) that boots the kernel and writes the spec to public/openapi.json gives you a static artifact you can validate in CI, diff in review, and serve from a CDN.

Serve docs behind a firewall in non-prod. Register or leave enabled the docs route only in dev/staging, or put it behind your existing security.yaml access control. The spec leaks your entire method surface and parameter shapes.

Validate in CI. Pipe the dumped spec through swagger-cli validate or openapi-spec-validator as a test step. This catches malformed schemas from method metadata before they reach consumers, and is the single highest-value integration for a package this small.

Pair with Swagger UI / Redoc. The bundle gives you the machine-readable spec, not a UI. A one-file static HTML page (Redoc via CDN) pointing at your spec URL is the usual companion; symfony/asset and a Twig template is enough.

Gotchas and Tips

• No Flex recipe, one maintainer, zero dependents. Treat this as infrastructure you co-own: pin the exact version ("yoanm/symfony-jsonrpc-http-server-openapi-doc": "x.y.z"), commit composer.lock, and expect to read the source when something misbehaves. Budget for a possible fork.
• JSON-RPC is not REST, and OpenAPI is a REST-shaped format. The generated paths are a convention (usually one POST path per method with a single params object). Swagger UI's "Try it out" will not produce a correct JSON-RPC envelope unless the spec author has modelled it deliberately — document the {"jsonrpc":"2.0","method":...,"params":...,"id":...} envelope separately, or your consumers will file bugs.
• Cache invalidation bites. If the spec is built from container metadata, changing a method's description/schema requires bin/console cache:clear (and in prod, a full deploy that rebuilds the container). A docs change that "doesn't show up" is almost always the container cache, not the bundle.
• Route collisions. The bundle registers a controller route; if you already own a path like /openapi.json or /docs, you'll get a duplicate-route error on cache warmup. Check debug:router and override the path in config.
• Extension points are service decoration and compiler passes. To alter schemas, decorate the spec-builder service (find its ID with bin/console debug:container | grep -i openapi) rather than editing vendor code. The bundle is small, so debug:container plus Resources/config/services.yaml is usually enough to find the seam.
• Debug by dumping the array. The most direct troubleshooting path is a throwaway command that fetches the spec service, converts it to an array, and var_dumps it — you see exactly what the generator produced before serialization hides anything.
• Symfony/PHP version drift. Last release is recent, but with one maintainer and no dependents, constraint ranges may lag behind the newest Symfony minor. If composer update fails, check the symfony/* constraints in the package's composer.json before assuming your app is at fault.