protoc-gen-swagger does not generate parameters other than body and path parameters.

[winglq]

1. my proto file is as following. It's an example of google api design.

syntax="proto3";

package book;
import "google/api/annotations.proto";
import "google/protobuf/field_mask.proto";

service BookService {
  // Updates a book.
  rpc UpdateBook(UpdateBookRequest) returns (Book) {
    // Update maps to HTTP PATCH. Resource name is mapped to a URL path.
    // Resource is contained in the HTTP request body.
    option (google.api.http) = {
      // Note the URL template variable which captures the resource name of the
      // book to update.
      patch: "/v1/{book.name=shelves/*/books/*}"
      body: "book"
    };
  }
}

message UpdateBookRequest {
  // The book resource which replaces the resource on the server.
  Book book = 1;

  // The update mask applies to the resource. For the `FieldMask` definition,
  // see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask
  google.protobuf.FieldMask update_mask = 2;
}

message Book {
  string name = 1;
  string author = 2;
}

2. Use protoc-gen-swagger to generate a swagger file. I got the following json output.

{
  "swagger": "2.0",
  "info": {
    "title": "app/book.proto",
    "version": "version not set"
  },
  "schemes": [
    "http",
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/v1/{book.name=shelves/*/books/*}": {
      "patch": {
        "summary": "Updates a book.",
        "operationId": "UpdateBook",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/bookBook"
            }
          }
        },
        "parameters": [
          {
            "name": "book.name",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "description": "The book resource which replaces the resource on the server.",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/bookBook"
            }
          }
        ],
        "tags": [
          "BookService"
        ]
      }
    }
  },
  "definitions": {
    "bookBook": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "author": {
          "type": "string"
        }
      }
    },
....

3. The update_mask parameter is missing in the output.
   BTW: I tried the master branch and the latest tagged release, and got the same result.

What did you expect to happen instead:

An update_mask should be there.

[johanbrandhorst]

Hi @winglq! It seems you stumbled upon our automatic patch-support by mistake! Yes, the update-mask is not there, because it's not necessary if you use JSON, where you can omit fields. See https://grpc-ecosystem.github.io/grpc-gateway/docs/patch.html

[johanbrandhorst]

If you would really like the update_mask to show up, you can turn off patch handling with the allow_patch_feature=false setting to the generator: https://github.com/grpc-ecosystem/grpc-gateway/blob/master/protoc-gen-grpc-gateway/main.go#L35.

[winglq]

@johanbrandhorst thanks for the explaination.

I tried to change the UpdateBookRequest as following:

message UpdateBookRequest {
  // The book resource which replaces the resource on the server.
  Book book = 1;

  string title = 2;
}

But I could not get the title parameter.

Here is the parameter section of the output.

        "parameters": [
          {
            "name": "book.name",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "description": "The book resource which replaces the resource on the server.",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/bookBook"
            }
          }
        ],

According to google api design doc , title should be mapped to a query parameter.

Not sure whether this behavior is also by design. Thanks.

[johanbrandhorst]

I would also expect the title to turn up as a query parameter, however, this could just be a big in the swagger generator. Could you see if the server parsing still works? Please raise a separate bug for this behaviour.

[winglq]

A new issue #1012 is opened.