How to generate request body documentation for API explorer for runtime RPCs?

Runtime Framework
, ,
1

The Nakama API explorer shows the request body structure for inbuilt Nakama RPCs.

For our custom RPCs as well, we want to add little documentation that would help the Unity developers integrate the RPCs easily by following the request body structure without having to communicate back and forth - even for the changes.

If it is not possible with the default configuration, what would be the good ways to generate documentation for the RPC APIs so that we can integrate easily just by having documentation as comments around the RPC calls or handlers?

I’m looking to achieve functionality similar to the apiDoc outcome.

  1. Versions: Nakama {3.5}, {Windows, Mac, Linux binary or Docker}, {client library (SDK) and version}
  2. Server Framework Runtime language (If relevant) {Go, TS/JS, Lua}
{code or log snippet}

:tv: Media:

Blockquote

2

Hey thealphadollar, great question! Basically what you need is a documentation generator that works by taking .proto files as input. The rpcs themselves will need to be documented by hand, but you can inline in the comments for each message in the .proto what its intended RPC use is. There are a lot of different generators out there. Here’s one: GitHub - pseudomuto/protoc-gen-doc: Documentation generator plugin for Google Protocol Buffers

3

Thanks for the response.

However, I don’t completely understand why we need to write the .proto files. As far as my understanding goes, for the RPCs, we just have to return (string, err) that gets converted to the protobuf format automatically. What we are currently doing is something like below,

type User struct {

	// The id of the user's account.
	Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
	// The username of the user's account.
	Username string `protobuf:"bytes,2,opt,name=username,proto3" json:"username,omitempty"`
}

However, if my understanding is incorrect, I’d definitely like to understand how we can use Nakama Protobuf instead of the responses over the REST API as that would save us a huge network call bandwidth.

4

Hey @lugehorsam , can you please help me here? I’d appreciate if you can let me know a decent amount of time we are expected to wait and tagging directly before receiving a response.

5

Hi @thealphadollar if you are using JSON then you’ll have to document your API by hand or maintain a swagger schema. If you’d like any sort of response time guarantees or even estimates you’d have to reach out to support@heroiclabs.com and discuss a support contract.

The forum can only be a good faith effort to help everyone in the community as best we can, and empower them to help each other!