Mark a number of libraries deprecated

config.yaml

@@ -332,6 +332,17 @@ packages:
       - youtube:v3
       - youtubeAnalytics:v2
       - youtubereporting:v1 # https://developers.google.com/youtube/reporting/v1/reports/
+    deprecation_map:
+      cloudfunctions:v1: google_cloud_functions_v2
+      cloudfunctions:v2: google_cloud_functions_v2
+      iam:v1: google_cloud_iam_v1
+      iam:v2: google_cloud_iam_v1
+      iamcredentials:v1: google_cloud_iam_v1
+      language:v1: google_cloud_language_v2
+      language:v2: google_cloud_language_v2
+      logging:v2: google_cloud_logging_v2
+      secretmanager:v1: google_cloud_secretmanager_v1
+      storage:v1: google_cloud_storage
 
   googleapis_beta:
     version: 9.1.0-wip

discoveryapis_generator/lib/discoveryapis_generator.dart

@@ -24,13 +24,15 @@ List<GenerateResult> generateApiPackage(
   Pubspec pubspec, {
   bool deleteExisting = true,
   required Set<String> skipTests,
+  Map<String, String> deprecationMap = const {},
 }) {
   final apisPackageGenerator = ApisPackageGenerator(
     descriptions,
     pubspec,
     outputDirectory,
     deleteExisting: deleteExisting,
     skipTests: skipTests,
+    deprecationMap: deprecationMap,
   );
 
   return apisPackageGenerator.generateApiPackage();
@@ -42,6 +44,7 @@ List<GenerateResult> generateAllLibraries(
   Pubspec pubspec, {
   bool deleteExisting = true,
   required Set<String> skipTests,
+  Map<String, String> deprecationMap = const {},
 }) {
   final apiDescriptions = Directory(inputDirectory)
       .listSync()
@@ -59,6 +62,7 @@ List<GenerateResult> generateAllLibraries(
     pubspec,
     deleteExisting: deleteExisting,
     skipTests: skipTests,
+    deprecationMap: deprecationMap,
   );
 }
 

discoveryapis_generator/lib/src/apis_package_generator.dart

@@ -34,6 +34,7 @@ class ApisPackageGenerator with DedupeMixin {
   final Pubspec pubspec;
   final bool deleteExisting;
   final Set<String> skipTests;
+  final Map<String, String> deprecationMap;
 
   /// [descriptions] is a list of API descriptions we want to generate code for.
   ///
@@ -48,6 +49,7 @@ class ApisPackageGenerator with DedupeMixin {
     this.packageFolderPath, {
     this.deleteExisting = true,
     required this.skipTests,
+    this.deprecationMap = const {},
   });
 
   /// Starts generating the API package with all the APIs given in the
@@ -113,7 +115,11 @@ ${requestHeadersField(pubspec.version)}
         try {
           // Create API itself.
           Directory(apiFolderPath).createSync();
-          final apiLibrary = _generateApiLibrary(apiVersionFile, description);
+          final apiLibrary = _generateApiLibrary(
+            apiVersionFile,
+            description,
+            deprecationTargetPackage: deprecationMap[description.id],
+          );
 
           // Create Test for API.
           Directory(apiTestFolderPath).createSync();
@@ -167,9 +173,14 @@ ${duplicateItems.map((e) => e.definition).join('\n\n')}
 
   DartApiLibrary _generateApiLibrary(
     String outputFile,
-    RestDescription description,
-  ) => libraryDeduplicateLogic(() {
-    final lib = DartApiLibrary.build(description, isPackage: true);
+    RestDescription description, {
+    String? deprecationTargetPackage,
+  }) => libraryDeduplicateLogic(() {
+    final lib = DartApiLibrary.build(
+      description,
+      isPackage: true,
+      deprecationTargetPackage: deprecationTargetPackage,
+    );
     writeDartSource(outputFile, lib.librarySource);
     return lib;
   });

discoveryapis_generator/lib/src/dart_api_library.dart

@@ -82,12 +82,14 @@ class DartApiLibrary extends BaseApiLibrary {
   final bool isPackage;
   late final bool exposeMedia;
   late final String libraryName;
+  final String? deprecationTargetPackage;
 
   /// Generates a API library for [description].
   DartApiLibrary.build(
     RestDescription description, {
     required this.isPackage,
     super.useCorePrefixes,
+    this.deprecationTargetPackage,
   }) : super(description, 'Api') {
     libraryName = ApiLibraryNamer.libraryName(
       description.name,
@@ -114,8 +116,31 @@ class DartApiLibrary extends BaseApiLibrary {
       apiClass,
     ).asDartDoc(0).trim();
 
+    if (deprecationTargetPackage != null) {
+      final warningBlock =
+          '''
+/// > [!WARNING]
+/// > This API is deprecated. Use
+/// > [`package:$deprecationTargetPackage`](https://pub.dev/packages/$deprecationTargetPackage)
+/// > instead.
+///''';
+      if (libraryComments.isEmpty) {
+        libraryComments = warningBlock;
+      } else {
+        libraryComments = '$warningBlock\n$libraryComments';
+      }
+    }
+
     if (libraryComments.isNotEmpty) {
-      libraryComments = '$libraryComments\nlibrary;';
+      if (deprecationTargetPackage != null) {
+        libraryComments =
+            '$libraryComments\n'
+            '@${imports.core.ref()}Deprecated('
+            '\'Use package:$deprecationTargetPackage\')\n'
+            'library;';
+      } else {
+        libraryComments = '$libraryComments\nlibrary;';
+      }
     }
 
     final result = [