hz annotation

The IDL annotation provided by hz.

Supported api annotations

Field annotation can be used

for parameter binding and validation

Method annotation can be used to generate code that related to route registration

Supported api annotations

hz

Field annotation tag description can be referenced supported-tags.

Field annotation
annotation description
api.raw_body generate “raw_body” tag
api.query generate “query” tag
api.header generate “header” tag
api.cookie generate “cookie” tag
api.body generate “json” tag
api.path generate “path” tag
api.form generate “form” tag
api.go_tag (protobuf)
go.tag (thrift)		 passing go_tag through will generate the content defined in go_tag
api.vd generate “vd” tag
api.none Generate “-” tag, please refer to api.none annotation usage for details
Method annotation
annotation description
api.get define GET methods and routes
api.post define POST methods and routes
api.put define PUT methods and routes
api.delete define DELETE methods and routes
api.patch define PATCH methods and routes
api.options define OPTIONS methods and routes
api.head define HEAD methods and routes
api.any define ANY methods and routes

hz client

In addition to the annotations provided by hz, one additional annotation has been added for client scenarios.

Client annotation
annotation description
api.base_domain specify the default access request domain

Usage

Field annotation

Thrift:

struct Demo {
    1: string Demo (api.query="demo", api.path="demo");
    2: string GoTag (go.tag="goTag:"tag"");
    3: string Vd (api.vd="$!='your string'");
}

Protobuf:

message Demo {
    string Demo = 1[(api.query) = "demo", (api.path) = "demo"];
    string GoTag = 2[(api.go_tag) = "goTag:\"tag\""];
    string Vd = 3[(api.vd) = "$!='your string'"];
}

Method annotation

Thrift:

service Demo {
    Resp Method(1: Req request) (api.get="/route");
}

Protobuf:

service Demo {
    rpc Method(Req) returns(Resp) {
        option (api.get) = "/route";
    }
}

Client annotation

Thrift：

struct Demo {
    1: string HeaderValue (api.header="file1");
}

service Demo {
    Resp Method(1: Req request) (api.get="/route");
}(
    api.base_domain="http://127.0.0.1:8888";
)

Protobuf:

message Demo {
    string HeaderValue = 1[(api.header) = "file1"];
}

service Demo {
    rpc Method(Req) returns(Resp) {
        option (api.get) = "/route";
    }
    option (api.base_domain) = "http://127.0.0.1:8888";
}

Last modified March 22, 2024 : docs: optimize hertz vd tag description (#995) (ee7bb09)