Protobuf specification

Protobuf writing and conventions

Detailed examples referencehere

Standards and conventions

• Protobuf specification referencehere

• Add OpenAPI documentation reference used in protobufhere, protoc-gen-restIntegrated in the command

syntax = "proto3";

// Convention: format here is: {interface_type}.{interface_version}.{service_name}[.service_category]
// Where {interface_type}, {interface_version}, [service_category] will be used in the REST service to generate the route prefix
// Can be modified via the api and version fields in ajard.api.http
// For example, the following package name generates the route prefix /api/v1/docs
//
// {service_name} is used when generating gateway code to determine the client name, for example:
// conn, err := client.NewClient(grpc.Protocol, config.GetString("asjard.topology.services.{hello}.name", "{hello}")).Conn()
// If asjard.service.instance.name is modified, it can be changed via asjard.topology.service.hello.name
package api.v1.example.docs;

option go_package = "protos-repo/example/api/v1/hello";

import "github.com/asjard/protobuf/http.proto";
import "github.com/asjard/protobuf/validate.proto";
import "github.com/asjard/protobuf/mq.proto";

// Features to be implemented
// Only write one service per proto file
// If the group field is not configured in REST, the service name becomes the value of the group field
service Hello {
    // You can define routing information for the entire service
    // option(asjard.api.serviceHttp) = {api: "api", versin: "v1", group:"hello", writer_name: "custome_writer"}
    // Feature description,
    // Supports Markdown
    // Can be rendered in the interface description of the OpenAPI documentation
    // Rendered in the route description of the REST service
    rpc Say(SayReq) returns (SayResp) {
        // If exposing a REST service externally, write the following route information
        // There can be multiple route entries
        option (asjard.api.http) = {
            // Key is the request method, supports get, put, post, delete, patch, header
            // Value is the request path, relative path
            // Full path is interface type + / + interface version + / + interface group + / + request path
            // GET /api/v1/hello
            get : "/"
            // If not empty, use the interface category here
            api : ""
            // If not empty, use the interface version here
            version : ""
            // If not empty, use the interface group here; if all empty, use the plural name of the service
            group : ""
            // Custom writer for the current interface
            writer_name : ""
        };
        option (asjard.api.http) = {
            // POST /api/v1/hello
            post : "/"
        };
        option (asjard.api.http) = {
            // DELETE /api/v1/hello/{name}
            delete : "/{name}"
        };
        option (asjard.api.http) = {
            // PUT /api/v1/hello/{name}
            put : "/{name}"
        };
        option (asjard.api.http) = {
            // GET /openapi/v2/groupName/hello/{name}
            get : "/hello/{name}"
            group : "groupName"
            api : "openapi"
            version : "v2"
        };
        // Provide MQ service
        option (asjard.api.mq) = {
        };
    };
}

// Request parameters
message SayReq {
    // Field description
    // Will be rendered into the OpenAPI field description
    string name = 1 [ (asjard.api.validate).rules = "required,max=20" ];
}

// Response
message SayResp { string message = 2; }