Swagger and RPC Discoverability

Swagger/OpenAPI is excellent at documenting HTTP endpoints. In a REST API, each business operation is usually represented by a route, so Swagger naturally lists many operations.

In JSON-RPC, the HTTP surface may contain only one endpoint:

POST /rpc

Swagger can document this endpoint, but it cannot automatically infer every possible JSON-RPC method inside the request body unless the application exposes that metadata separately.

Practical Solution

Keep Swagger for the HTTP surface and expose a separate method catalog for the RPC surface:

app.MapGet("/rpc/methods", (IEnumerable methodDescriptors) =>
{
    List methods = methodDescriptors
        .OrderBy(methodDescriptor => methodDescriptor.Method)
        .ToList();

    return Results.Ok(methods);
})
.WithName("JsonRpcMethodCatalog")
.WithSummary("Lists registered JSON-RPC methods.")
.WithDescription("Returns the discoverable method catalog for methods handled behind the single /rpc endpoint.");

The above endpoint registration uses a custom RpcMethodDescriptor class to describe each method, including its name and request/response types:

public class RpcMethodDescriptor
{
    public string Method { get; set; } = string.Empty;
    public string Description { get; set; } = string.Empty;
    public string RequestType { get; set; } = string.Empty;
    public string ResponseType { get; set; } = string.Empty;        
    public string ExampleRequestJson { get; set; } = string.Empty;
}

The actual method catalog is populated by the same assembly scanning code that registers handlers, so it stays up to date without manual maintenance. The following example shows what the method catalog returned by the /rpc/methods endpoint might look like:

[
  {
    "method": "Bank.MakeDeposit",
    "requestType": "MakeDepositRequest",
    "responseType": "MakeDepositResponse"
  },
  {
    "method": "Shipment.Search",
    "requestType": "ShipmentSearchRequest",
    "responseType": "ShipmentSearchResponse"
  }
]

This makes the system discoverable without pretending that every RPC method is a separate REST endpoint:

 

Table of Content Operation-Oriented APIs and AI Tools Previous: Automatic Discovery and Registration Next: AI-Friendly Operation Catalog

 

---

Business Process Programming in .Net
© 2004–2026 Laskarzhevsky Software Inc.
Unless otherwise noted, the content of this website is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).
Code examples are provided under the MIT License.
You are free to share and adapt the material provided that appropriate credit is given and any modifications are clearly indicated.
The information provided on this website is for educational purposes only.
The author and publisher make no warranties regarding the completeness or suitability of the information and are not responsible for any damages resulting from its use.