JSON RPC API文档工具有哪些？Swagger能否用于编写？有无更优工具？

Great question! Let's break this down step by step since JSON-RPC has some unique quirks compared to REST APIs—tools like Swagger were built with REST in mind, so they don't always fit perfectly for RPC-style APIs.

Here are some solid options that work well for documenting JSON-RPC APIs, ranging from dedicated tools to flexible general-purpose ones:

• Postman：While it's widely known for API testing, Postman excels at documenting JSON-RPC too. You can create a collection where each RPC method is a separate request, pre-configured with the required jsonrpc: "2.0" structure, method name, params, and id. You can add detailed descriptions for each method, parameter definitions, example requests/responses, and even share a public documentation link with your team or users. The interactive testing feature is a huge plus for anyone trying to use your API.
• jsonrpc-docgen：This is a dedicated JSON-RPC documentation generator that pulls directly from your code comments (like JSDoc for JavaScript/TypeScript). Just annotate your RPC methods with parameter types, return value schemas, and descriptions, and it will generate clean, static HTML docs. It’s perfect for keeping your documentation in sync with your implementation without manual work.
• RPCDoc：Another tool built specifically for JSON-RPC. You define your API methods in a simple YAML format, specifying things like method names, parameter types, error codes, and examples. RPCDoc then renders this into an interactive, easy-to-navigate documentation page that lets users understand and test your API methods quickly.
• Custom Markdown + Static Site Generators：If you want full control over your docs' structure and style, go with Markdown combined with tools like MkDocs or Hugo. You can write detailed explanations for each RPC method, include code snippets, and organize content exactly how you want. This is great for teams that need highly customized documentation with branding or specific workflow guides.

Yes, but it’s a workaround at best. Swagger (now part of OpenAPI) was designed for REST APIs, which rely on HTTP verbs and resource paths—JSON-RPC uses a single POST endpoint where all method calls are sent in the request body.

To make Swagger work for JSON-RPC, you’d have to:

• Define a single POST endpoint that accepts all RPC requests.
• Create a request schema that includes the mandatory jsonrpc, method, params, and id fields.
• Add examples for each individual RPC method’s request and response payloads.

The big drawbacks here are:

• Swagger’s UI will display one generic endpoint instead of individual RPC methods, which is confusing for users trying to find specific functionality.
• You can’t use Swagger’s built-in features like method grouping or automatic parameter validation in a way that feels natural for JSON-RPC.
• It feels like forcing a square peg into a round hole—your documentation won’t be as intuitive or clean as it would be with a tool made for JSON-RPC.

If you want a tool that fits JSON-RPC natively instead of hacking Swagger, the dedicated options I mentioned earlier are your best bet:

• jsonrpc-docgen：Automates docs from code comments, keeping your implementation and docs in sync.
• RPCDoc：Purpose-built for JSON-RPC, with a simple definition format and clean interactive docs.
• Postman Collections：Offers an intuitive way to organize and document each RPC method separately, with built-in testing capabilities.

These tools understand JSON-RPC’s structure and will present your API in a way that makes sense to users, without the awkward workarounds required for Swagger.

Hope this helps you choose the right tool for your JSON-RPC documentation needs! 🚀

内容的提问来源于stack exchange，提问作者user2287258