Change example field

.circleci/config.yml

@@ -41,7 +41,7 @@ executors:
       password1: '3ec86b2e5a431be2d72c'
       GLOG_logtostderr: '1'
     docker:
-      - image: docker.pkg.github.com/grpc-ecosystem/grpc-gateway/build-env:1.14
+      - image: docker.pkg.github.com/grpc-ecosystem/grpc-gateway/build-env:1.15
         auth:
           username: gateway-ci-user
           password: ${password0}${password1}

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 && \

docs/_docs/v2-migration.md

@@ -36,6 +36,27 @@ option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = {
 
 The bazel rule has been renamed `protoc_gen_openapiv2`.
 
+## The example field in the OpenAPI annotations is now a string
+
+This was a `google.protobuf.Any` type, but it was only used for the JSON
+representation, and it was breaking some tools and it was generally unclear to the user
+how it works. It is now a string instead. The value is copied verbatim to
+the output OpenAPI file. Remember to escape any quotes in the strings.
+
+For example, if you had an example that looked like this:
+
+```protobuf
+example: { value: '{ "uuid": "0cf361e1-4b44-483d-a159-54dabdf7e814" }' }
+```
+
+It would now look like this:
+
+```protobuf
+example: "{\"uuid\": \"0cf361e1-4b44-483d-a159-54dabdf7e814\"}"
+```
+
+See `a_bit_of_everything.proto` in the example protos for more examples.
+
 ## We now use the camelCase JSON names by default
 See
 [the original issue](https://github.com/grpc-ecosystem/grpc-gateway/issues/375)

examples/internal/proto/examplepb/a_bit_of_everything.proto

@@ -196,13 +196,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: "{\"uuid\": \"0cf361e1-4b44-483d-a159-54dabdf7e814\"}"
 	};
 
 	// Nested is nested type.
 	message Nested {
 		option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
-			example: { value: '{ "ok": "TRUE" }' }
+			example: "{ \"ok\": \"TRUE\" }"
 		};
 		// name is nested field.
 		string name = 1;
@@ -278,7 +278,7 @@ message ABitOfEverything {
 // ABitOfEverythingRepeated is used to validate repeated path parameter functionality
 message ABitOfEverythingRepeated {
 	option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
-		example: { value: '{ "path_repeated_bool_value": [true, true, false, true], "path_repeated_int32_value": [1, 2, 3] }' }
+		example: "{\"path_repeated_bool_value\": [true, true, false, true], \"path_repeated_int32_value\": [1, 2, 3]}"
 	};
 
 	// repeated values. they are comma-separated in path

protoc-gen-openapiv2/internal/genopenapi/BUILD.bazel

@@ -41,7 +41,6 @@ go_test(
         "//protoc-gen-openapiv2/options:go_default_library",
         "//runtime:go_default_library",
         "@com_github_google_go_cmp//cmp: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-openapiv2/internal/genopenapi/template.go

@@ -1850,8 +1850,8 @@ func openapiSchemaFromProtoSchema(s *openapi_options.Schema, reg *descriptor.Reg
 	ret.schemaCore = protoJSONSchemaToOpenAPISchemaCore(s.GetJsonSchema(), reg, refs)
 	updateswaggerObjectFromJSONSchema(&ret, s.GetJsonSchema(), reg, data)
 
-	if s != nil && s.Example != nil {
-		ret.Example = json.RawMessage(s.Example.Value)
+	if s != nil && s.Example != "" {
+		ret.Example = json.RawMessage(s.Example)
 	}
 
 	return ret

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

@@ -10,7 +10,6 @@ import (
 
 	descriptorpb "github.com/golang/protobuf/protoc-gen-go/descriptor"
 	pluginpb "github.com/golang/protobuf/protoc-gen-go/plugin"
-	anypb "github.com/golang/protobuf/ptypes/any"
 	structpb "github.com/golang/protobuf/ptypes/struct"
 	"github.com/google/go-cmp/cmp"
 	"github.com/grpc-ecosystem/grpc-gateway/v2/internal/descriptor"
@@ -2727,10 +2726,7 @@ func TestRenderMessagesAsDefinition(t *testing.T) {
 			},
 			schema: map[string]openapi_options.Schema{
 				"Message": {
-					Example: &anypb.Any{
-						TypeUrl: "this_isnt_used",
-						Value:   []byte(`{"foo":"bar"}`),
-					},
+					Example: `{"foo":"bar"}`,
 				},
 			},
 			defs: map[string]openapiSchemaObject{
@@ -2747,9 +2743,7 @@ func TestRenderMessagesAsDefinition(t *testing.T) {
 			},
 			schema: map[string]openapi_options.Schema{
 				"Message": {
-					Example: &anypb.Any{
-						Value: []byte(`XXXX anything goes XXXX`),
-					},
+					Example: `XXXX anything goes XXXX`,
 				},
 			},
 			defs: map[string]openapiSchemaObject{