Symfony Jsonrpc Http Server Swagger Doc Laravel Package

Getting Started

This bundle is an add-on to yoanm/symfony-jsonrpc-http-server. You need a working JSON-RPC endpoint first; the doc bundle then introspects the registered methods and exposes a Swagger 2.0 document for them.

Minimal setup:

1. Install the doc bundle next to the server bundle:

   composer require yoanm/symfony-jsonrpc-http-server yoanm/symfony-jsonrpc-http-server-swagger-doc
   

2. Register the bundle if Flex does not do it automatically (config/bundles.php).
3. Add a minimal base document so the generated spec has required Swagger fields:

   # config/packages/yoanm_jsonrpc_http_server_swagger_doc.yaml
   yoanm_jsonrpc_http_server_swagger_doc:
       base_document:
           info:
               title: 'Acme JSON-RPC API'
               version: '1.0.0'
           host: 'api.example.test'
           basePath: '/'
           schemes: ['https']
   

   Confirm the exact key names with bin/console debug:config yoanm_jsonrpc_http_server_swagger_doc; the bundle's DependencyInjection/Configuration.php is the authoritative reference.
4. Find the generated doc route:

   bin/console debug:router | grep -i -E 'doc|swagger'
   

5. Register at least one method with the JSON-RPC server bundle, then request the doc route and paste the JSON into editor.swagger.io or import it into Postman.

Where to look first:

• The README of both bundles, especially the server bundle's method-registration examples.
• vendor/yoanm/symfony-jsonrpc-http-server-swagger-doc/src/DependencyInjection/Configuration.php for config keys.
• bin/console debug:container --tag=... and debug:router to see what the bundle actually registered.
• The method class / method metadata used by the server bundle, because that is what the doc generator reads.

The first real use case is almost always: expose the spec at a URL, load it into Swagger UI or Postman, and use it to agree on request/response shapes with frontend or integration teams.

Implementation Patterns

Treat method metadata as the single source of truth. The doc is derived from the methods registered with the JSON-RPC server. Put parameter names, types, required flags, and result types on the method definition itself, not in hand-maintained YAML. When a method changes, the doc changes with it. Hand-editing the generated document guarantees drift.

Use the base document for global concerns only. Put info, host, basePath, schemes, securityDefinitions, shared definitions, and tags in the configured base document. Keep operation-level details with the methods.

Gate the doc route by environment. Documentation routes are frequently left open. Restrict them in production with a firewall, when@dev / when@test config, or by generating a static file during CI instead of serving dynamically. If you serve it publicly, treat the spec as part of your API surface.

Pick a serving strategy deliberately:

• Dynamic Symfony route + Swagger UI for local and staging use.
• Dump the generated JSON to public/docs/swagger.json or an artifact during CI for versioned, reviewable docs.
• Feed it into NelmioApiDocBundle or a standalone Swagger UI container if you already have one.

Use the spec as a CI contract. Snapshot the generated JSON, diff it on pull requests, and validate it:

swagger-cli validate docs/swagger.json

Fail the build if a newly registered JSON-RPC method is missing from the document, or if a schema change was not reviewed. This is where a low-adoption package pays for itself: it gives you an enforceable contract without writing documentation by hand.

Drive clients and mocks from the doc. Import the spec into Postman, Prism, or a mock server for frontend work. For SDK generation, note that most modern generators expect OpenAPI 3, so convert first (for example with api-spec-converter) and inspect the output. Generated REST clients will not speak the JSON-RPC envelope out of the box; wrap them or generate only the schema types.

Add a method workflow. For each new JSON-RPC method: implement the method class with explicit parameter/result metadata, register it with the server bundle, clear the cache, refresh the doc, validate it, and update any checked-in snapshot or Postman collection. Keep this in the team's definition of done.

Use extension points sparingly. Add JSON-RPC-specific behavior through base-document x- vendor extensions (for example, documenting the envelope, jsonrpc, id, and error shape). If the bundle exposes a doc-builder service, decorate it rather than forking; use debug:container to find the service ID.

Gotchas and Tips

• Swagger 2.0, not OpenAPI 3. Modern tooling increasingly assumes 3.x. Expect to convert for SDK generators, and remember that nullable, oneOf, and $ref behavior differ between versions.
• JSON-RPC is not REST. The generated document describes method shapes, not the JSON-RPC transport semantics. Errors are returned inside a 200 response body, not as HTTP status codes, so Swagger's response-code model will mislead consumers unless you document a shared error definition and explain it.
• Positional vs named params. JSON-RPC allows both. Pick one convention and enforce it in your method definitions; otherwise the generated request schema will not match what clients actually send.
• Empty results and notifications. Methods that return nothing, or that are notifications without an id, need explicit handling. A missing or vague result schema is worse than a documented void.
• Method names become paths or operation identifiers. Dots, slashes, and unusual characters in JSON-RPC method names can produce awkward or invalid path output. Check the generated paths block after adding methods with non-trivial names.
• Clear the cache after changes. Symfony caches container/config and, depending on setup, the generated document. Run bin/console cache:clear when a method or base-document change does not appear.
• Version alignment matters. The doc bundle is tightly coupled to yoanm/symfony-jsonrpc-http-server and the underlying jsonrpc-server-common. Pin compatible versions and read the source when behavior is unclear; with zero dependents there is little community troubleshooting to lean on.
• Base-document merging can surprise you. Array merges may replace rather than append. Watch for collisions in definitions and securityDefinitions when combining the base document with generated content.
• Authentication mismatch. If your JSON-RPC endpoint uses HTTP basic, API keys, or a firewall, make sure securityDefinitions reflects the real transport-level scheme. JSON-RPC-level auth, if any, is not modeled by Swagger.
• CORS and UI hosting. A separately hosted Swagger UI needs CORS access to the doc URL and, if protected, a way to supply credentials.
• Debugging flow: dump the raw JSON, validate it, diff it against the previous version, then inspect the method metadata feeding it. Most "missing method" or "wrong schema" bugs are registration or metadata problems, not generator bugs.
• Do not hand-edit generated output. It will be overwritten. If you need permanent additions, put them in the base document or a decorator.
• Low adoption is a real risk. The package is maintained (recent release) but niche. Budget time to read the bundle source, and keep your integration behind a small internal service or command so you can swap it out if needed.