🚀 Feature
Problem
When using protoc-gen-openapiv2, enum fields always expose the full enum definition in generated Swagger/OpenAPI schemas.
Example:
enum ResourceType {
RESOURCE_TYPE_UNSPECIFIED = 0;
RESOURCE_TYPE_USER = 1;
RESOURCE_TYPE_GROUP = 2;
RESOURCE_TYPE_SERVICE = 3;
RESOURCE_TYPE_INTERNAL = 4;
}
message ResourceRequest {
ResourceType resource_type = 1;
}
The generated OpenAPI schema exposes all enum values globally.
However, in some APIs we want:
strong typing internally using protobuf enums
generated language constants
enum validation
but only a restricted subset (or alternate representation) exposed in OpenAPI for a particular field usage.
For example, RESOURCE_TYPE_INTERNAL may be intended only for internal services and should not appear in public API documentation.
Currently the only workaround is to:
change enum fields to string
duplicate enum names manually in validation annotations
maintain synchronization manually between enum definitions and string validation lists
Example workaround:
string resource_type = 1 [
(validate.rules).string = {
in: [
"RESOURCE_TYPE_USER",
"RESOURCE_TYPE_GROUP",
"RESOURCE_TYPE_SERVICE"
]
}
];
This introduces:
duplicated source of truth
maintenance burden
risk of enum/string drift
loss of protobuf enum typing in API contracts
Requested Feature
Support field-level OpenAPI enum projection/restriction.
Example idea:
ResourceType resource_type = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
enum_subset: [
"RESOURCE_TYPE_USER",
"RESOURCE_TYPE_GROUP",
"RESOURCE_TYPE_SERVICE"
]
}
];
Expected behavior:
protobuf field remains enum typed
generated SDKs retain enum safety
OpenAPI schema exposes only selected enum values for that field
avoids converting enums to strings purely for documentation concerns
Additional Context
This is especially useful for:
public vs internal API exposure
partial enum availability
🚀 Feature
Problem
When using protoc-gen-openapiv2, enum fields always expose the full enum definition in generated Swagger/OpenAPI schemas.
Example:
enum ResourceType {
RESOURCE_TYPE_UNSPECIFIED = 0;
RESOURCE_TYPE_USER = 1;
RESOURCE_TYPE_GROUP = 2;
RESOURCE_TYPE_SERVICE = 3;
RESOURCE_TYPE_INTERNAL = 4;
}
message ResourceRequest {
ResourceType resource_type = 1;
}
The generated OpenAPI schema exposes all enum values globally.
However, in some APIs we want:
strong typing internally using protobuf enums
generated language constants
enum validation
but only a restricted subset (or alternate representation) exposed in OpenAPI for a particular field usage.
For example, RESOURCE_TYPE_INTERNAL may be intended only for internal services and should not appear in public API documentation.
Currently the only workaround is to:
change enum fields to string
duplicate enum names manually in validation annotations
maintain synchronization manually between enum definitions and string validation lists
Example workaround:
string resource_type = 1 [
(validate.rules).string = {
in: [
"RESOURCE_TYPE_USER",
"RESOURCE_TYPE_GROUP",
"RESOURCE_TYPE_SERVICE"
]
}
];
This introduces:
duplicated source of truth
maintenance burden
risk of enum/string drift
loss of protobuf enum typing in API contracts
Requested Feature
Support field-level OpenAPI enum projection/restriction.
Example idea:
ResourceType resource_type = 1 [
(grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
enum_subset: [
"RESOURCE_TYPE_USER",
"RESOURCE_TYPE_GROUP",
"RESOURCE_TYPE_SERVICE"
]
}
];
Expected behavior:
protobuf field remains enum typed
generated SDKs retain enum safety
OpenAPI schema exposes only selected enum values for that field
avoids converting enums to strings purely for documentation concerns
Additional Context
This is especially useful for:
public vs internal API exposure
partial enum availability