Help us understand the problem. What is going on with this article?

痒いところに手が届くprotocol buffersの書き方

最近swaggerをprotoに移植する作業をしたので、その過程で調べたことをメモする。
主にprotocol buffersからprotoc-gen-swaggerを使ってswaggerをgenerateする人向け。

descriptionやexampleの文字列を改行する

message IdName {
    option (grpc.gateway.protoc_gen_swagger.options.openapiv2_schema) = {
        json_schema: {
            description: "情報"
                         "テスト"
            required: [
                "id",
                "name"
            ]
        }
        example: { 
            value: "{" 
                        '"id": "1",'
                        '"name": "田中 太郎"'
                    "}"
        }
    };

    int32 id = 1 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {
        description: "primary key"
    }];

    string name = 2 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {
        description: "name"
    }];
}

response_bodyのトップレベルをobjectではなく配列にする

{
  "users": [
    {
      "id": "1",
      "name": "test"
    },
    {
      "id": "2",
      "name": "test2"
    }
  ]
}

ではなく、

[
  {
    "id": "1",
    "name": "test"
  },
  {
    "id": "2",
    "name": "test2"
  }
]

にしたい
その場合はresponse_bodyに指定する

message IdNameResponse {
    repeated IdName id_names = 1 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {
        description: "id name array"
    }];
}

rpc GetIdName(google.protobuf.Empty) returns (user.IdNameResponse) {
    option (google.api.http) = {
        get: "/user/id_name"
        response_body: "id_names"
    };
}

protoc-gen-swaggerを実行する際に、以下のoptionをつける必要がある

allow_repeated_fields_in_body=true

headersの定義

IDはreserveされているものの、未実装
なのでextensionを使って表現する
参考: https://github.com/grpc-ecosystem/grpc-gateway/blob/e1a127c6f7cf2006c77a16dbc0face2a43f2094a/protoc-gen-swagger/options/openapiv2.proto#L85

rpc GetIdName(google.protobuf.Empty) returns (user.IdName) {
    option (google.api.http) = {
        get: "/user/id_name"
    };
    option (grpc.gateway.protoc_gen_swagger.options.openapiv2_operation) = {
    description: "Get user's id and name"
    extensions: {
        key: "x-hoge";
        value {
            string_value: "integer";
        }
    };
}

200以外のresponseの追加

どうやら現状では200を201にするとかはできないらしい
参考: https://github.com/grpc-ecosystem/grpc-gateway/issues/517#issuecomment-536180156
なので、200レスポンスも出てしまうが、201も併記する

rpc CreateIdName(user.IdName) returns (user.IdName) {
    option (google.api.http) = {
        post: "/user/id_name"
        body : "*"
    };
    option (grpc.gateway.protoc_gen_swagger.options.openapiv2_operation) = {
        description: "Create user"
        responses: {
            key: "201";
            value: {
                description: "Successful response"
                schema: {
                    json_schema: {
                        ref: ".user.IdName";
                    }
                }
            }
        };
        responses: {
            key: "401";
            value: {
                description: "Unauthorized"
                schema: {
                    json_schema: {
                        ref: ".error.Error";
                    }
                }
            }
        };
    };
}

defaultの入れ方

int32 id = 1 [(grpc.gateway.protoc_gen_swagger.options.openapiv2_field) = {
    description: "primary key"
    default: "1"
}];

defaultはstringなのでintegerであっても文字列で入れてやる必要がある

その他tips

IDを自動で振り直す

a_thug
C/C++ 組込み系 FirmWare Node.js Ruby on Rails Vue.js swift
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした