fix: add api_version breadcrumb to client docs (#4018)

noahdietz · web-flow · commit a2b2179874e6 · 2025-12-12T14:33:25.000-05:00
Adds simple breadcrumb comment to client class commentary including the `google.api.api_version` value that this client was generated based on and sends in its requests, as per AIP-4236. This breadcrumb will allow client users to reference the API version used by the client in other API artifacts e.g. product documentation. Fixes internal tracking bug http://b/467138606, child of http://b/467065424.
diff --git a/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java b/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java
@@ -114,6 +114,12 @@ public static List<CommentStatement> createClassHeaderComments(
       classHeaderJavadocBuilder = classHeaderJavadocBuilder.addUnescapedComment(descriptionComment);
     }
 
+    // Include google.api.api_version breadcrumb comment.
+    if (service.hasApiVersion()) {
+      classHeaderJavadocBuilder.addParagraph(
+          String.format("This client uses %s version %s.", service.name(), service.apiVersion()));
+    }
+
     // Service introduction.
     classHeaderJavadocBuilder.addParagraph(SERVICE_DESCRIPTION_INTRO_STRING);
     classHeaderJavadocBuilder.addSampleCode(classMethodSampleCode);
diff --git a/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpcrest/goldens/EchoClient.golden b/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpcrest/goldens/EchoClient.golden
@@ -30,8 +30,10 @@ import javax.annotation.Generated;
 
 // AUTO-GENERATED DOCUMENTATION AND CLASS.
 /**
- * This class provides the ability to make remote calls to the backing service through method calls
- * that map to API methods. Sample code to get started:
+ * This client uses Echo version foo_version_for_tests.
+ *
+ * <p>This class provides the ability to make remote calls to the backing service through method
+ * calls that map to API methods. Sample code to get started:
  *
  * <pre>{@code
  * // This snippet has been automatically generated and should be regarded as a code template only.
diff --git a/java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/EchoClient.java b/java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/EchoClient.java
@@ -59,6 +59,8 @@
  * 'x-goog-request-params' metadata key on any method to have the values echoed in the response
  * headers.
  *
+ * <p>This client uses Echo version v1_20240408.
+ *
  * <p>This class provides the ability to make remote calls to the backing service through method
  * calls that map to API methods. Sample code to get started:
  *

Original file line number	Diff line number	Diff line change
`@@ -59,6 +59,8 @@`
`59`	`59`	`* 'x-goog-request-params' metadata key on any method to have the values echoed in the response`
`60`	`60`	`* headers.`
`61`	`61`	`*`
	`62`	`+ * <p>This client uses Echo version v1_20240408.`
	`63`	`+ *`
`62`	`64`	`* <p>This class provides the ability to make remote calls to the backing service through method`
`63`	`65`	`* calls that map to API methods. Sample code to get started:`
`64`	`66`	`*`