GRPC Annotations in Tonic (Rust)


One pretty neat feature to have when operating a GRPC API is documentation. It can be almost cost-free by using annotations. With Tonic, it is possible to have the endpoints auto documented into a Swagger or OpenAPI documentation.

A Tonic GRPC server working with annotations

Lets try for this api specification,


    syntax = "proto3";
    package api;
    option go_package = "api";

    import "google/api/annotations.proto";

    message Message {
        string value = 1;

    service EchoService {
        rpc Echo(Message) returns (Message) {
                option (google.api.http) = {
                post: "/v1/example/echo"
                body: "*"

and this rust implementation,


    use tonic::{transport::Server, Request, Response, Status};

    use crate::api::echo_service_server::{EchoService, EchoServiceServer};
    use api::Message;

    pub mod api {

    #[derive(Debug, Default)]
    pub struct EchoAPI {}

    impl EchoService for EchoAPI {
        async fn echo(
            request: Request<Message>,
        ) -> Result<Response<Message>, Status> {
            let message = request.into_inner();

            println!("received {:?}", message.value);

            Ok(Response::new(Message { value: "response".into() }))

    async fn main() -> Result<(), Box<dyn std::error::Error>> {
        let addr = "".parse()?;

        println!("listening on port {:?}", addr);




    use failure::{Error};

    fn main() -> Result<(), Error> {
            &["googleapis", "grpc"],


and in Cargo.toml:

failure             = "^0.1" // ༼◕_◕༽ anyhow would be better
prost               = "0.6"
tonic               = { version = "^0.3", features = ["tls"] }
tokio               = { version = "^0.2", features = ["macros"] }

failure             = "^0.1"
tonic-build         = "^0.3"

then add .gitmodules:

    [submodule "googleapis"]
    path = googleapis
    url =

don’t forget to git submodule update --remote

Generating a swagger documentation

You need golang, the protobuf compiler and swagger

To install protoc on linux:

    #! /bin/bash
    apt-get -qq update
    apt-get install -y  build-essential wget zip

    rm -f *.zip
    mv bin/* /usr/local/bin
    mv include/* /usr/local/include/
    protoc --version

To install/update gprc gateway extensions:

    go get -u &&\
            go get -u     &&\
            go get -u

To generate swagger documentation:

    protoc  -I/usr/local/include -I.            \
        -I$GOPATH/src                       \
        -I$GOPATH/src/ \
        --swagger_out=logtostderr=true:.    \
docker run -p 80:8080 -e BASE_URL=/ -e SWAGGER_JSON=/swag/echo.swagger.json -v `pwd`:/swag swaggerapi/swagger-ui

With this documentation and observability offered by opentelemetry-rust, you can have production ready grpc api in Rust.

From here, just enjoy the ride.


© All rights reserved. Powered by Astro with ♥.