Deprecate example field (#1637)

* Update contribution guide to use 1.15 generator

* Deprecate example field in favor of example_string

The example field using google.protobuf.Any
was pretty silly and just happened to work because
of how we were using it. It's confusing to users and breaks some tooling,
so it is best deprecated.

This is an unfortunate break from the "each field maps to the openapiv2 schema"
precedent we've maintained so far, but there is
no other good way that I can think of to safely deprecate
this.

Author: johanbrandhorst

CONTRIBUTING.md

@@ -25,7 +25,7 @@ All submissions, including submissions by project members, require review.
 Great! It should be as simple as this (run from the root of the directory):
 
 ```bash
-docker run -v $(pwd):/src/grpc-gateway --rm docker.pkg.github.com/grpc-ecosystem/grpc-gateway/build-env:1.14 \
+docker run -v $(pwd):/src/grpc-gateway --rm docker.pkg.github.com/grpc-ecosystem/grpc-gateway/build-env:1.15 \
     /bin/bash -c 'cd /src/grpc-gateway && \
         make realclean && \
         make examples && \

examples/internal/proto/examplepb/a_bit_of_everything.pb.go

@@ -194,13 +194,13 @@ message ABitOfEverything {
 			url: "https://github.com/grpc-ecosystem/grpc-gateway";
 			description: "Find out more about ABitOfEverything";
 		}
-		example: { value: '{ "uuid": "0cf361e1-4b44-483d-a159-54dabdf7e814" }' }
+		example_string: "{\"uuid\": \"0cf361e1-4b44-483d-a159-54dabdf7e814\"}"
 	};
 
 	// Nested is nested type.
 	message Nested {
 		option (grpc.gateway.protoc_gen_swagger.options.openapiv2_schema) = {
-			example: { value: '{ "ok": "TRUE" }' }
+			example_string: "{\"ok\": \"TRUE\"}"
 		};
 		// name is nested field.
 		string name = 1;
@@ -276,7 +276,7 @@ message ABitOfEverything {
 // ABitOfEverythingRepeated is used to validate repeated path parameter functionality
 message ABitOfEverythingRepeated {
 	option (grpc.gateway.protoc_gen_swagger.options.openapiv2_schema) = {
-		example: { value: '{ "path_repeated_bool_value": [true, true, false, true], "path_repeated_int32_value": [1, 2, 3] }' }
+		example_string: "{\"path_repeated_bool_value\": [true, true, false, true], \"path_repeated_int32_value\": [1, 2, 3]}"
 	};
 
 	// repeated values. they are comma-separated in path

examples/internal/proto/examplepb/a_bit_of_everything.proto

@@ -40,7 +40,6 @@ go_test(
         "//protoc-gen-grpc-gateway/httprule:go_default_library",
         "//protoc-gen-swagger/options:go_default_library",
         "@com_github_golang_protobuf//proto:go_default_library",
-        "@io_bazel_rules_go//proto/wkt:any_go_proto",
         "@io_bazel_rules_go//proto/wkt:compiler_plugin_go_proto",
         "@io_bazel_rules_go//proto/wkt:descriptor_go_proto",
         "@io_bazel_rules_go//proto/wkt:struct_go_proto",

protoc-gen-swagger/genswagger/BUILD.bazel

@@ -1877,6 +1877,9 @@ func swaggerSchemaFromProtoSchema(s *swagger_options.Schema, reg *descriptor.Reg
 	if s != nil && s.Example != nil {
 		ret.Example = json.RawMessage(s.Example.Value)
 	}
+	if s != nil && s.ExampleString != "" {
+		ret.Example = json.RawMessage(s.ExampleString)
+	}
 
 	return ret
 }

protoc-gen-swagger/genswagger/template.go

@@ -11,7 +11,6 @@ import (
 	"github.com/golang/protobuf/proto"
 	protodescriptor "github.com/golang/protobuf/protoc-gen-go/descriptor"
 	plugin "github.com/golang/protobuf/protoc-gen-go/plugin"
-	"github.com/golang/protobuf/ptypes/any"
 	structpb "github.com/golang/protobuf/ptypes/struct"
 	"github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway/descriptor"
 	"github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway/httprule"
@@ -2515,10 +2514,7 @@ func TestRenderMessagesAsDefinition(t *testing.T) {
 			},
 			schema: map[string]swagger_options.Schema{
 				"Message": swagger_options.Schema{
-					Example: &any.Any{
-						TypeUrl: "this_isnt_used",
-						Value:   []byte(`{"foo":"bar"}`),
-					},
+					ExampleString: `{"foo":"bar"}`,
 				},
 			},
 			defs: map[string]swaggerSchemaObject{
@@ -2535,9 +2531,7 @@ func TestRenderMessagesAsDefinition(t *testing.T) {
 			},
 			schema: map[string]swagger_options.Schema{
 				"Message": swagger_options.Schema{
-					Example: &any.Any{
-						Value: []byte(`XXXX anything goes XXXX`),
-					},
+					ExampleString: `XXXX anything goes XXXX`,
 				},
 			},
 			defs: map[string]swaggerSchemaObject{

protoc-gen-swagger/genswagger/template_test.go

@@ -334,7 +334,13 @@ message Schema {
   // Additional external documentation for this schema.
   ExternalDocumentation external_docs = 5;
   // A free-form property to include an example of an instance for this schema.
-  google.protobuf.Any example = 6;
+  // Deprecated, please use example_string instead.
+  google.protobuf.Any example = 6 [
+    deprecated = true
+  ];
+  // A free-form property to include a JSON example of this field. This is copied
+  // verbatim to the output swagger.json. Quotes must be escaped.
+  string example_string = 7;
 }
 
 // `JSONSchema` represents properties from JSON Schema taken, and as used, in