feat(gengapic): add snippets (googleapis#1220)

* add option omit-snippets (default: false)
* add snippet support to gengapic.go and example.go
* copy snippets/metadata and helpers from google-cloud-go
* continue to skip unimplemented streaming examples and snippets
* improve unit test coverage

Author: quartzmo

.github/snippet-bot.yml

@@ -1,2 +1,7 @@
 aggregateChecks: false
 alwaysCreateStatusCheck: false
+
+# The generator prints region tags and snippet-bot wants to correct
+# the printing code.
+ignoreFiles:
+  - "internal/**"

README.md

@@ -101,6 +101,8 @@ The configuration supported by the plugin option includes:
     * Not enabled by default.
     * Only effective when `rest` is included as a `transport` to be generated.
 
+  * `omit-snippets`: disable generation of code snippets to the `internal/generated/snippets` path. The default is `false`.
+
 Bazel
 -----
 
@@ -165,6 +167,8 @@ following attributes:
     * Default is `False`.
     * Only effective when `rest` is included as a `transport` to be generated.
 
+  * `omit_snippets`: if `True`, code snippets will be generated to the `internal/generated/snippets` path. The default is `false`.
+
 Docker Wrapper
 --------------
 The generator can also be executed via a Docker container. The image containes `protoc`, the microgenerator

internal/gengapic/BUILD.bazel

@@ -19,6 +19,7 @@ go_library(
         "mixins.go",
         "options.go",
         "paging.go",
+        "snippets.go",
         "stream.go",
         "test_utils.go",
     ],
@@ -30,6 +31,7 @@ go_library(
         "//internal/license",
         "//internal/pbinfo",
         "//internal/printer",
+        "//internal/snippets",
         "@com_github_ghodss_yaml//:yaml",
         "@com_gitlab_golang_commonmark_markdown//:markdown",
         "@com_google_cloud_go_iam//apiv1/iampb",
@@ -46,6 +48,7 @@ go_library(
         "@org_golang_google_protobuf//proto",
         "@org_golang_google_protobuf//reflect/protodesc",
         "@org_golang_google_protobuf//runtime/protoiface",
+        "@org_golang_google_protobuf//types/descriptorpb",
     ],
 )
 
@@ -70,6 +73,7 @@ go_test(
     deps = [
         "//internal/grpc_service_config",
         "//internal/pbinfo",
+        "//internal/snippets",
         "//internal/txtdiff",
         "@com_github_google_go_cmp//cmp",
         "@com_google_cloud_go_longrunning//autogen/longrunningpb",
@@ -78,6 +82,7 @@ go_test(
         "@go_googleapis//google/api:httpbody_go_proto",
         "@go_googleapis//google/api:serviceconfig_go_proto",
         "@go_googleapis//google/cloud:extended_operations_go_proto",
+        "@go_googleapis//google/longrunning:longrunning_go_proto",
         "@go_googleapis//google/rpc:code_go_proto",
         "@io_bazel_rules_go//proto/wkt:compiler_plugin_go_proto",
         "@io_bazel_rules_go//proto/wkt:descriptor_go_proto",

internal/gengapic/client_init.go

@@ -242,21 +242,25 @@ func (g *generator) genClientWrapperMethod(m *descriptor.MethodDescriptorProto,
 	}
 
 	// Generate method documentation just before any method is generated.
-	g.methodDoc(m)
+	g.methodDoc(m, serv)
 
 	if m.GetOutputType() == emptyType {
-		p("func (c *%s) %s(ctx context.Context, req *%s.%s, opts ...gax.CallOption) error {",
-			clientTypeName, m.GetName(), inSpec.Name, inType.GetName())
+		reqTyp := fmt.Sprintf("%s.%s", inSpec.Name, inType.GetName())
+		p("func (c *%s) %s(ctx context.Context, req *%s, opts ...gax.CallOption) error {",
+			clientTypeName, m.GetName(), reqTyp)
 		p("    return c.internalClient.%s(ctx, req, opts...)", m.GetName())
 		p("}")
 		p("")
+
+		g.addSnippetsMetadataParams(m, serv.GetName(), reqTyp)
 		return nil
 	}
 
 	if g.isLRO(m) {
+		reqTyp := fmt.Sprintf("%s.%s", inSpec.Name, inType.GetName())
 		lroType := lroTypeName(m.GetName())
-		p("func (c *%s) %s(ctx context.Context, req *%s.%s, opts ...gax.CallOption) (*%s, error) {",
-			clientTypeName, m.GetName(), inSpec.Name, inType.GetName(), lroType)
+		p("func (c *%s) %s(ctx context.Context, req *%s, opts ...gax.CallOption) (*%s, error) {",
+			clientTypeName, m.GetName(), reqTyp, lroType)
 		p("    return c.internalClient.%s(ctx, req, opts...)", m.GetName())
 		p("}")
 		p("")
@@ -266,21 +270,28 @@ func (g *generator) genClientWrapperMethod(m *descriptor.MethodDescriptorProto,
 		p("  return c.internalClient.%s(name)", lroType)
 		p("}")
 		p("")
+
+		g.addSnippetsMetadataParams(m, serv.GetName(), reqTyp)
+		g.addSnippetsMetadataResult(m, serv.GetName(), lroType)
 		return nil
 	}
 
 	if pf, _, err := g.getPagingFields(m); err != nil {
 		return err
 	} else if pf != nil {
+		reqTyp := fmt.Sprintf("%s.%s", inSpec.Name, inType.GetName())
 		iter, err := g.iterTypeOf(pf)
 		if err != nil {
 			return err
 		}
-		p("func (c *%s) %s(ctx context.Context, req *%s.%s, opts ...gax.CallOption) *%s {",
-			clientTypeName, m.GetName(), inSpec.Name, inType.GetName(), iter.iterTypeName)
+		p("func (c *%s) %s(ctx context.Context, req *%s, opts ...gax.CallOption) *%s {",
+			clientTypeName, m.GetName(), reqTyp, iter.iterTypeName)
 		p("    return c.internalClient.%s(ctx, req, opts...)", m.GetName())
 		p("}")
 		p("")
+
+		g.addSnippetsMetadataParams(m, serv.GetName(), reqTyp)
+		g.addSnippetsMetadataResult(m, serv.GetName(), iter.iterTypeName)
 		return nil
 	}
 
@@ -291,34 +302,48 @@ func (g *generator) genClientWrapperMethod(m *descriptor.MethodDescriptorProto,
 			return err
 		}
 
-		p("func (c *%s) %s(ctx context.Context, opts ...gax.CallOption) (%s.%s_%sClient, error) {",
-			clientTypeName, m.GetName(), servSpec.Name, serv.GetName(), m.GetName())
+		retTyp := fmt.Sprintf("%s.%s_%sClient", servSpec.Name, serv.GetName(), m.GetName())
+		p("func (c *%s) %s(ctx context.Context, opts ...gax.CallOption) (%s, error) {",
+			clientTypeName, m.GetName(), retTyp)
 		p("    return c.internalClient.%s(ctx, opts...)", m.GetName())
 		p("}")
 		p("")
+
+		g.addSnippetsMetadataParams(m, serv.GetName(), "")
+		g.addSnippetsMetadataResult(m, serv.GetName(), retTyp)
 		return nil
 	case m.GetServerStreaming():
 		servSpec, err := g.descInfo.ImportSpec(serv)
 		if err != nil {
 			return err
 		}
-		p("func (c *%s) %s(ctx context.Context, req *%s.%s, opts ...gax.CallOption) (%s.%s_%sClient, error) {",
-			clientTypeName, m.GetName(), inSpec.Name, inType.GetName(), servSpec.Name, serv.GetName(), m.GetName())
+
+		reqTyp := fmt.Sprintf("%s.%s", inSpec.Name, inType.GetName())
+		retTyp := fmt.Sprintf("%s.%s_%sClient", servSpec.Name, serv.GetName(), m.GetName())
+		p("func (c *%s) %s(ctx context.Context, req *%s, opts ...gax.CallOption) (%s, error) {",
+			clientTypeName, m.GetName(), reqTyp, retTyp)
 		p("    return c.internalClient.%s(ctx, req, opts...)", m.GetName())
 		p("}")
 		p("")
+
+		g.addSnippetsMetadataParams(m, serv.GetName(), reqTyp)
+		g.addSnippetsMetadataResult(m, serv.GetName(), retTyp)
 		return nil
 	default:
+		reqTyp := fmt.Sprintf("%s.%s", inSpec.Name, inType.GetName())
 		retTyp, err := g.returnType(m)
 		if err != nil {
 			return err
 		}
 
-		p("func (c *%s) %s(ctx context.Context, req *%s.%s, opts ...gax.CallOption) (%s, error) {",
-			clientTypeName, m.GetName(), inSpec.Name, inType.GetName(), retTyp)
+		p("func (c *%s) %s(ctx context.Context, req *%s, opts ...gax.CallOption) (%s, error) {",
+			clientTypeName, m.GetName(), reqTyp, retTyp)
 		p("    return c.internalClient.%s(ctx, req, opts...)", m.GetName())
 		p("}")
 		p("")
+
+		g.addSnippetsMetadataParams(m, serv.GetName(), reqTyp)
+		g.addSnippetsMetadataResult(m, serv.GetName(), retTyp)
 		return nil
 	}
 

internal/gengapic/client_init_test.go

@@ -24,6 +24,7 @@ import (
 	"github.com/google/go-cmp/cmp"
 	conf "github.com/googleapis/gapic-generator-go/internal/grpc_service_config"
 	"github.com/googleapis/gapic-generator-go/internal/pbinfo"
+	"github.com/googleapis/gapic-generator-go/internal/snippets"
 	"github.com/googleapis/gapic-generator-go/internal/txtdiff"
 	"google.golang.org/genproto/googleapis/api/annotations"
 	"google.golang.org/genproto/googleapis/api/serviceconfig"
@@ -385,6 +386,7 @@ func TestClientInit(t *testing.T) {
 		customOpServ *descriptor.ServiceDescriptorProto
 		parameter    *string
 		imports      map[pbinfo.ImportSpec]bool
+		wantNumSnps  int
 	}{
 		{
 			tstName: "foo_client_init",
@@ -405,6 +407,7 @@ func TestClientInit(t *testing.T) {
 				{Name: "locationpb", Path: "google.golang.org/genproto/googleapis/cloud/location"}: true,
 				{Name: "mypackagepb", Path: "github.com/googleapis/mypackage"}:                     true,
 			},
+			wantNumSnps: 6,
 		},
 		{
 			tstName: "foo_rest_client_init",
@@ -424,6 +427,7 @@ func TestClientInit(t *testing.T) {
 				{Path: "net/http"}:                                                    true,
 				{Name: "httptransport", Path: "google.golang.org/api/transport/http"}: true,
 			},
+			wantNumSnps: 6,
 		},
 		{
 			tstName:   "empty_client_init",
@@ -441,6 +445,7 @@ func TestClientInit(t *testing.T) {
 				{Name: "mypackagepb", Path: "github.com/googleapis/mypackage"}:        true,
 				{Name: "httptransport", Path: "google.golang.org/api/transport/http"}: true,
 			},
+			wantNumSnps: 1,
 		},
 		{
 			tstName: "lro_client_init",
@@ -460,6 +465,7 @@ func TestClientInit(t *testing.T) {
 				{Path: "google.golang.org/grpc"}:          true,
 				{Path: "google.golang.org/grpc/metadata"}: true,
 			},
+			wantNumSnps: 6,
 		},
 		{
 			tstName:   "deprecated_client_init",
@@ -477,6 +483,7 @@ func TestClientInit(t *testing.T) {
 				{Path: "google.golang.org/grpc/metadata"}:             true,
 				{Path: "net/http"}:                                    true,
 			},
+			wantNumSnps: 1,
 		},
 		{
 			tstName:      "custom_op_init",
@@ -493,6 +500,7 @@ func TestClientInit(t *testing.T) {
 				{Path: "net/http"}:                                                    true,
 				{Name: "httptransport", Path: "google.golang.org/api/transport/http"}: true,
 			},
+			wantNumSnps: 1,
 		},
 	} {
 		fds := append(mixinDescriptors(), &descriptor.FileDescriptorProto{
@@ -539,13 +547,40 @@ func TestClientInit(t *testing.T) {
 		}
 
 		g.reset()
+		sm := snippets.NewMetadata("mypackage", "github.com/googleapis/mypackage", "mypackagego")
+		sm.AddService(tst.serv.GetName(), "mypackage.googleapis.com")
+		for _, m := range tst.serv.GetMethod() {
+			sm.AddMethod(tst.serv.GetName(), m.GetName(), "mypackage", tst.serv.GetName(), 50)
+		}
+		for _, m := range g.getMixinMethods() {
+			sm.AddMethod(tst.serv.GetName(), m.GetName(), "mypackage", tst.serv.GetName(), 50)
+		}
+		g.snippetMetadata = sm
 		g.makeClients(tst.serv, tst.servName)
 
 		if diff := cmp.Diff(g.imports, tst.imports); diff != "" {
 			t.Errorf("ClientInit(%s) imports got(-),want(+):\n%s", tst.tstName, diff)
 		}
 
 		txtdiff.Diff(t, tst.tstName, g.pt.String(), filepath.Join("testdata", tst.tstName+".want"))
+		mi := g.snippetMetadata.ToMetadataIndex()
+		if got := len(mi.Snippets); got != tst.wantNumSnps {
+			t.Errorf("%s: got %d want len %d", t.Name(), tst.wantNumSnps, got)
+		}
+		for _, snp := range mi.Snippets {
+			if got := snp.ClientMethod.Parameters[0].Name; got != "ctx" {
+				t.Errorf("%s: got %s want ctx,", t.Name(), got)
+			}
+			if got := snp.ClientMethod.Parameters[1].Name; got != "req" {
+				t.Errorf("%s: got %s want req,", t.Name(), got)
+			}
+			if got := snp.ClientMethod.Parameters[2].Name; got != "opts" {
+				t.Errorf("%s: got %s want opts,", t.Name(), got)
+			}
+			if snp.ClientMethod.ShortName != "CancelOperation" && snp.ClientMethod.ShortName != "DeleteOperation" && snp.ClientMethod.ResultType == "" {
+				t.Errorf("%s: got empty string, want ResultType for %s", t.Name(), snp.ClientMethod.ShortName)
+			}
+		}
 	}
 }
 

internal/gengapic/example.go

@@ -74,6 +74,8 @@ func (g *generator) exampleInitClient(pkgName, servName string) {
 	p("  // TODO: Handle error.")
 	p("}")
 	p("defer c.Close()")
+
+	g.imports[pbinfo.ImportSpec{Path: "context"}] = true
 }
 
 func (g *generator) exampleMethod(pkgName, servName string, m *descriptor.MethodDescriptorProto) error {

internal/gengapic/example_test.go

@@ -22,6 +22,7 @@ import (
 	"github.com/golang/protobuf/protoc-gen-go/descriptor"
 	"github.com/google/go-cmp/cmp"
 	"github.com/googleapis/gapic-generator-go/internal/pbinfo"
+	"github.com/googleapis/gapic-generator-go/internal/snippets"
 	"github.com/googleapis/gapic-generator-go/internal/txtdiff"
 	"google.golang.org/genproto/googleapis/api/annotations"
 	"google.golang.org/genproto/googleapis/api/serviceconfig"
@@ -276,6 +277,88 @@ func TestExample(t *testing.T) {
 	}
 }
 
+func TestGenSnippetFile(t *testing.T) {
+	var g generator
+	g.imports = map[pbinfo.ImportSpec]bool{}
+	g.serviceConfig = &serviceconfig.Service{
+		Apis: []*apipb.Api{
+			{Name: "google.cloud.bigquery.migration.v2.MigrationService"},
+		},
+	}
+
+	protoPkg := "google.cloud.bigquery.migration.v2"
+	libPkg := "cloud.google.com/go/bigquery/migration/apiv2"
+	pkgName := "bigquerymigration"
+	g.snippetMetadata = snippets.NewMetadata(protoPkg, libPkg, pkgName)
+
+	inputType := &descriptor.DescriptorProto{
+		Name: proto.String("CreateMigrationWorkflowRequest"),
+	}
+	outputType := &descriptor.DescriptorProto{
+		Name: proto.String("MigrationWorkflow"),
+	}
+
+	file := &descriptor.FileDescriptorProto{
+		Options: &descriptor.FileOptions{
+			GoPackage: proto.String("cloud.google.com/go/bigquery/migration/apiv2/migrationpb"),
+		},
+		Package: proto.String(protoPkg),
+	}
+
+	files := []*descriptor.FileDescriptorProto{}
+	g.descInfo = pbinfo.Of(files)
+	for _, typ := range []*descriptor.DescriptorProto{
+		inputType, outputType,
+	} {
+		g.descInfo.Type[".google.cloud.bigquery.migration.v2."+typ.GetName()] = typ
+		g.descInfo.ParentFile[typ] = file
+	}
+
+	serv := &descriptor.ServiceDescriptorProto{
+		Name: proto.String("MigrationService"),
+		Method: []*descriptor.MethodDescriptorProto{
+			{
+				Name:       proto.String("CreateMigrationWorkflow"),
+				InputType:  proto.String(".google.cloud.bigquery.migration.v2.CreateMigrationWorkflowRequest"),
+				OutputType: proto.String(".google.cloud.bigquery.migration.v2.MigrationWorkflow"),
+			},
+		},
+	}
+
+	for _, tst := range []struct {
+		tstName string
+		options options
+		imports map[pbinfo.ImportSpec]bool
+	}{
+		{
+			tstName: "snippet",
+			options: options{
+				pkgName:    "migration",
+				transports: []transport{grpc, rest},
+			},
+			imports: map[pbinfo.ImportSpec]bool{
+				{Path: "context"}: true,
+				{Name: "migrationpb", Path: "cloud.google.com/go/bigquery/migration/apiv2/migrationpb"}: true,
+			},
+		},
+	} {
+		g.reset()
+		g.opts = &tst.options
+		defaultHost := "bigquerymigration.googleapis.com"
+		g.snippetMetadata.AddService(serv.GetName(), defaultHost)
+		err := g.genSnippetFile(serv, serv.Method[0])
+		if err != nil {
+			t.Fatal(err)
+		}
+		g.commit(filepath.Join(g.opts.outDir, "temp", "snippets", "main.go"), "main")
+		if diff := cmp.Diff(g.imports, tst.imports); diff != "" {
+			t.Errorf("TestExample(%s): imports got(-),want(+):\n%s", tst.tstName, diff)
+		}
+		got := *g.resp.File[0].Content + *g.resp.File[1].Content
+		txtdiff.Diff(t, tst.tstName, got, filepath.Join("testdata", tst.tstName+".want"))
+	}
+}
+
 func commonTypes(g *generator) {
 	empty := &descriptor.DescriptorProto{
 		Name: proto.String("Empty"),