Extend google.protobuf.EnumOptions

docs/docs/mapping/customizing_openapi_output.md

@@ -22,7 +22,7 @@ message MyMessage {
 
 ## Using proto options
 
-You can define options on your Protocol Buffer services, operations, messages, and field definitions to customize your Open API output. For instance, to customize the [OpenAPI Schema Object](https://swagger.io/specification/v2/#schemaObject) for messages and fields:
+You can define options on your Protocol Buffer services, operations, messages, enums and field definitions to customize your Open API output. For instance, to customize the [OpenAPI Schema Object](https://swagger.io/specification/v2/#schemaObject) for messages and fields:
 
 ```protobuf
 import "protoc-gen-openapiv2/options/annotations.proto";
@@ -51,6 +51,35 @@ message ABitOfEverything {
 }
 ```
 
+Enums can be customized like messages:
+
+```protobuf
+// NumericEnum is one or zero.
+enum NumericEnum {
+  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_enum) = {
+    json_schema: {
+      title: "NumericEnum"
+      description: "NumericEnum is one or zero."
+      extensions: {
+        key: "x-a-bit-of-everything-foo";
+        value {
+          string_value: "bar";
+        }
+      }
+    }
+    external_docs: {
+      url: "https://github.com/grpc-ecosystem/grpc-gateway";
+      description: "Find out more about ABitOfEverything";
+    }
+    example: "\"ZERO\""
+  };
+  // ZERO means 0
+  ZERO = 0;
+  // ONE means 1
+  ONE = 1;
+}
+```
+
 Operations can also be customized:
 
 ```protobuf
@@ -579,3 +608,4 @@ definitions:
 ```
 
 {% endraw %}
+

examples/internal/clients/abe/api/swagger.yaml

@@ -4544,12 +4544,17 @@ definitions:
         $ref: "#/definitions/examplepbErrorObject"
   examplepbNumericEnum:
     type: "string"
-    description: "NumericEnum is one or zero.\n\n - ZERO: ZERO means 0\n - ONE: ONE\
-      \ means 1"
+    externalDocs:
+      description: "Find out more about ABitOfEverything"
+      url: "https://github.com/grpc-ecosystem/grpc-gateway"
+    title: "NumericEnum"
+    description: "NumericEnum is one or zero."
+    example: "ZERO"
     enum:
     - "ZERO"
     - "ONE"
     default: "ZERO"
+    x-a-bit-of-everything-foo: "bar"
   examplepbSnakeEnumResponse:
     type: "object"
   examplepbsnake_case_0_enum:

examples/internal/clients/abe/model_examplepb_numeric_enum.go

@@ -9,7 +9,7 @@
  */
 
 package abe
-// ExamplepbNumericEnum : NumericEnum is one or zero.   - ZERO: ZERO means 0  - ONE: ONE means 1
+// ExamplepbNumericEnum : NumericEnum is one or zero.
 type ExamplepbNumericEnum string
 
 // List of examplepbNumericEnum

examples/internal/proto/examplepb/a_bit_of_everything.proto

@@ -424,6 +424,28 @@ message MessageWithBody {
 
 // NumericEnum is one or zero.
 enum NumericEnum {
+  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_enum) = {
+    json_schema: {
+      title: "NumericEnum"
+      description: "NumericEnum is one or zero."
+      required: [
+        "uuid",
+        "int64_value",
+        "double_value"
+      ]
+      extensions: {
+        key: "x-a-bit-of-everything-foo";
+        value {
+          string_value: "bar";
+        }
+      }
+    }
+    external_docs: {
+      url: "https://github.com/grpc-ecosystem/grpc-gateway";
+      description: "Find out more about ABitOfEverything";
+    }
+    example: "\"ZERO\""
+  };
   // ZERO means 0
   ZERO = 0;
   // ONE means 1

examples/internal/proto/examplepb/a_bit_of_everything.swagger.json

@@ -6485,12 +6485,24 @@
     },
     "examplepbNumericEnum": {
       "type": "string",
+      "example": "\"ZERO\"",
       "enum": [
         "ZERO",
         "ONE"
       ],
       "default": "ZERO",
-      "description": "NumericEnum is one or zero.\n\n - ZERO: ZERO means 0\n - ONE: ONE means 1"
+      "description": "NumericEnum is one or zero.",
+      "title": "NumericEnum",
+      "externalDocs": {
+        "description": "Find out more about ABitOfEverything",
+        "url": "https://github.com/grpc-ecosystem/grpc-gateway"
+      },
+      "required": [
+        "uuid",
+        "int64Value",
+        "doubleValue"
+      ],
+      "x-a-bit-of-everything-foo": "bar"
     },
     "examplepbSnakeEnumResponse": {
       "type": "object"

examples/internal/proto/examplepb/generated_input.swagger.json

@@ -311,12 +311,24 @@
     },
     "examplepbNumericEnum": {
       "type": "string",
+      "example": "\"ZERO\"",
       "enum": [
         "ZERO",
         "ONE"
       ],
       "default": "ZERO",
-      "description": "NumericEnum is one or zero.\n\n - ZERO: ZERO means 0\n - ONE: ONE means 1"
+      "description": "NumericEnum is one or zero.",
+      "title": "NumericEnum",
+      "externalDocs": {
+        "description": "Find out more about ABitOfEverything",
+        "url": "https://github.com/grpc-ecosystem/grpc-gateway"
+      },
+      "required": [
+        "uuid",
+        "int64Value",
+        "doubleValue"
+      ],
+      "x-a-bit-of-everything-foo": "bar"
     },
     "pathenumPathEnum": {
       "type": "string",

examples/internal/proto/examplepb/stream.swagger.json

@@ -437,12 +437,24 @@
     },
     "examplepbNumericEnum": {
       "type": "string",
+      "example": "\"ZERO\"",
       "enum": [
         "ZERO",
         "ONE"
       ],
       "default": "ZERO",
-      "description": "NumericEnum is one or zero.\n\n - ZERO: ZERO means 0\n - ONE: ONE means 1"
+      "description": "NumericEnum is one or zero.",
+      "title": "NumericEnum",
+      "externalDocs": {
+        "description": "Find out more about ABitOfEverything",
+        "url": "https://github.com/grpc-ecosystem/grpc-gateway"
+      },
+      "required": [
+        "uuid",
+        "int64Value",
+        "doubleValue"
+      ],
+      "x-a-bit-of-everything-foo": "bar"
     },
     "pathenumPathEnum": {
       "type": "string",

protoc-gen-openapiv2/internal/genopenapi/template.go

@@ -813,6 +813,9 @@ func renderEnumerationsAsDefinition(enums enumMap, d openapiDefinitionsObject, r
 		if err := updateOpenAPIDataFromComments(reg, &enumSchemaObject, enum, enumComments, false); err != nil {
 			panic(err)
 		}
+		if schema, err := getEnumSchemaOption(reg, enum.EnumDescriptorProto); err == nil {
+			updateswaggerObjectFromSchema(&enumSchemaObject, schema, reg, nil)
+		}
 
 		d[swgName] = enumSchemaObject
 	}
@@ -2394,6 +2397,21 @@ func extractFieldBehaviorFromFieldDescriptor(fd *descriptorpb.FieldDescriptorPro
 	return opts, nil
 }
 
+func extractEnumSchemaFromEnumDescriptor(enum *descriptorpb.EnumDescriptorProto) (*openapi_options.Schema, error) {
+	if enum.Options == nil {
+		return nil, nil
+	}
+	if !proto.HasExtension(enum.Options, openapi_options.E_Openapiv2Enum) {
+		return nil, nil
+	}
+	ext := proto.GetExtension(enum.Options, openapi_options.E_Openapiv2Enum)
+	opts, ok := ext.(*openapi_options.Schema)
+	if !ok {
+		return nil, fmt.Errorf("extension is %T; want a openapi_options.Schema object", ext)
+	}
+	return opts, nil
+}
+
 func getFieldVisibilityOption(fd *descriptor.Field) *visibility.VisibilityRule {
 	if fd.Options == nil {
 		return nil
@@ -2525,6 +2543,17 @@ func getFieldBehaviorOption(reg *descriptor.Registry, fd *descriptor.Field) ([]a
 	return opts, nil
 }
 
+func getEnumSchemaOption(reg *descriptor.Registry, enum *descriptorpb.EnumDescriptorProto) (*openapi_options.Schema, error) {
+	opts, err := extractEnumSchemaFromEnumDescriptor(enum)
+	if err != nil {
+		return nil, err
+	}
+	if opts != nil {
+		return opts, nil
+	}
+	return opts, nil
+}
+
 func protoJSONSchemaToOpenAPISchemaCore(j *openapi_options.JSONSchema, reg *descriptor.Registry, refs refMap) schemaCore {
 	ret := schemaCore{}
 
@@ -2549,7 +2578,9 @@ func protoJSONSchemaToOpenAPISchemaCore(j *openapi_options.JSONSchema, reg *desc
 
 func updateswaggerObjectFromJSONSchema(s *openapiSchemaObject, j *openapi_options.JSONSchema, reg *descriptor.Registry, data interface{}) {
 	s.Title = j.GetTitle()
-	s.Description = j.GetDescription()
+	if j.GetDescription() != "" {
+		s.Description = j.GetDescription()
+	}
 	if reg.GetUseGoTemplate() {
 		s.Title = goTemplateComments(s.Title, data, reg)
 		s.Description = goTemplateComments(s.Description, data, reg)
@@ -2574,7 +2605,6 @@ func updateswaggerObjectFromJSONSchema(s *openapiSchemaObject, j *openapi_option
 		s.MaxLength = j.GetMaxLength()
 		s.MinLength = j.GetMinLength()
 		s.Pattern = j.GetPattern()
-		s.Default = j.GetDefault()
 		s.UniqueItems = j.GetUniqueItems()
 		s.MaxProperties = j.GetMaxProperties()
 		s.MinProperties = j.GetMinProperties()
@@ -2585,7 +2615,6 @@ func updateswaggerObjectFromJSONSchema(s *openapiSchemaObject, j *openapi_option
 		s.MultipleOf = j.GetMultipleOf()
 		s.ExclusiveMaximum = j.GetExclusiveMaximum()
 		s.ExclusiveMinimum = j.GetExclusiveMinimum()
-		s.Enum = j.GetEnum()
 	}
 	s.MaxItems = j.GetMaxItems()
 	s.MinItems = j.GetMinItems()
@@ -2596,7 +2625,12 @@ func updateswaggerObjectFromJSONSchema(s *openapiSchemaObject, j *openapi_option
 			s.Required[i] = casing.JSONCamelCase(r)
 		}
 	}
-	s.Enum = j.GetEnum()
+	if j.GetDefault() != "" {
+		s.Default = j.GetDefault()
+	}
+	if len(j.GetEnum()) != 0 {
+		s.Enum = j.GetEnum()
+	}
 	if j.GetExtensions() != nil {
 		exts, err := processExtensions(j.GetExtensions())
 		if err != nil {
@@ -2615,6 +2649,16 @@ func updateswaggerObjectFromJSONSchema(s *openapiSchemaObject, j *openapi_option
 	}
 }
 
+func updateswaggerObjectFromSchema(s *openapiSchemaObject, j *openapi_options.Schema, reg *descriptor.Registry, data interface{}) {
+	if j.GetJsonSchema() != nil {
+		updateswaggerObjectFromJSONSchema(s, j.GetJsonSchema(), reg, data)
+	}
+	if j.GetExample() != "" { // avoid overwrite example from JsonSchema with empty string
+		s.Example = RawExample(strconv.Quote(j.GetExample()))
+	}
+	s.ExternalDocs = protoExternalDocumentationToOpenAPIExternalDocumentation(j.GetExternalDocs(), reg, data)
+}
+
 func updateSwaggerObjectFromFieldBehavior(s *openapiSchemaObject, j []annotations.FieldBehavior, reg *descriptor.Registry, field *descriptor.Field) {
 	// Per the JSON Reference syntax: Any members other than "$ref" in a JSON Reference object SHALL be ignored.
 	// https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3