Grpc-gateway: Option for omitting zero enum value from generated Swagger

[jgiles]

It's pretty typical practice in proto APIs for enum types with no natural default to declare the 0 value as UNKNOWN (or similar). Often UNKNOWN is not a valid option, but is declared to differentiate the "unset" case.

JSON semantics are different: The "unset" case is explicit, because the field is not present in the map object.

Currently, the generated Swagger spec exposes such an "UNKNOWN" option as a legitimate choice, and records it as the default choice. For cases where "UNKNOWN" is not a legitimate choice and should not be recorded as such in API docs/generated client code.

Bug reports:

Fill in the following sections with explanations of what's gone wrong.

Steps you follow to reproduce the error:

Example input:

enum Type {
    UNKNOWN = 0;
    FOO = 1;
    BAR = 2;
}

Current Swagger type definition output:

    "Type": {
      "type": "string",
      "enum": [
        "UNKNOWN",
        "FOO",
        "BAR"
      ],
      "default": "UNKNOWN"
    }

What did you expect to happen instead:

An annotation or other option to emit:

    "Type": {
      "type": "string",
      "enum": [
        "FOO",
        "BAR"
      ]
    }

What's your theory on why it isn't working:

Current behavior is the safe default.

An option to adjust this would most likely take the form of a new EnumOption annotation, with boolean field omit_default or similar to control this behavior: https://github.com/grpc-ecosystem/grpc-gateway/blob/master/protoc-gen-swagger/options/annotations.proto

[johanbrandhorst]

Thanks for the detailed feature request. I think this sounds okay, but you're sure you want it as an annotation rather than a generator option to remove all the zero enums in a document?

[jgiles]

Well, I think all of the enums in my proto files would benefit from this behavior, but there could be enums where there is a natural default (or the zero value is otherwise valid/intentional), and you could imagine some project having a mix of those two cases.
But perhaps a flag would be sufficient for the vast majority of cases - if you control the enum definitions, you can structure them consistently.

[johanbrandhorst]

Considering you're the first to ask for this, if it's good enough for you it's probably good enough for an MVP :). Do you intend to submit a PR to cover this behaviour change?

[jgiles]

If a PR for adding the generator command-line flag would be well-received, I can try to take a stab at it at some point :-)

[achew22]

I assure you it would be well received 😁

[gpopovic]

Any news on this?