docs: refresh root README and point to google-cloud-dart (#782)

Direct Google Cloud users to `googleapis/google-cloud-dart` and refresh the root README for the current pub workspace and generator workflow.

- Point Google Cloud developers to `googleapis/google-cloud-dart` for ongoing Cloud and authentication work, noting the Cloud APIs already deprecated in `package:googleapis` while clarifying that Workspace, YouTube, and other Discovery APIs remain here.
- Replace legacy `Google Developers Console` walkthroughs, archived `dart-lang/googleapis_examples` links, and unused `images/` assets with links to `googleapis_auth/README.md`, `APIs & Services > Library`, the Flutter Google APIs guide, and an analyzed `package:googleapis/drive/v3.dart` ADC example.
- Update contributor instructions for the root pub workspace, `googleapis_auth` Chrome tests, `./tool/download.sh`, `./tool/local_rebuild.sh`, `./tool/verify_examples_setup.sh`, and `discovery/<package>/<api>__<version>.json` override diffs.
7 files changed
tree: 8263c337224eb831165265402e93354762032088
  1. .github/
  2. _googleapis_auth_e2e/
  3. _test/
  4. _test_package/
  5. discovery/
  6. discoveryapis_commons/
  7. discoveryapis_generator/
  8. generated/
  9. generator/
  10. googleapis_auth/
  11. overrides/
  12. resources/
  13. test_integration/
  14. tool/
  15. .gitignore
  16. .gitmodules
  17. analysis_options.yaml
  18. AUTHORS
  19. config.yaml
  20. CONTRIBUTING.md
  21. LICENSE
  22. mono_repo.yaml
  23. pubspec.yaml
  24. README.md
README.md

Dart packages for accessing RESTful Google APIs described by the API Discovery Service, along with OAuth 2.0 authentication helpers.

[!IMPORTANT]

Most future Google API and Google Cloud client development for Dart is happening in googleapis/google-cloud-dart. If you are targeting Google Cloud services, check google-cloud-dart first. Several Cloud APIs in package:googleapis (including Cloud Storage, Firestore, Secret Manager, Cloud Logging, IAM, Cloud Functions, Cloud Tasks, Compute Engine, and Natural Language) are already deprecated in favor of google_cloud_* packages.

Use the packages in this repository for Google Workspace (Drive, Gmail, Calendar, Sheets, Docs), YouTube, and other Discovery-based Google APIs not yet covered by google-cloud-dart.

Packages

PackageDescriptionVersion
googleapisGenerated Dart libraries for stable Google APIs described by the API Discovery Service.pub package
googleapis_betaGenerated Dart libraries for beta and preview Google APIs described by the API Discovery Service.pub package
googleapis_authObtain OAuth 2.0 access credentials and authenticated HTTP clients for Google services.pub package
discoveryapis_generatorGenerate Dart API client packages from API Discovery Service documents.pub package
_discoveryapis_commonsShared runtime support used by generated Discovery API packages (not intended for direct use).pub package

Getting started

  1. Find your API: Browse the available generated libraries and API documentation on pub.dev for package:googleapis and package:googleapis_beta.
  2. Set up a Google Cloud project: Create a project in the Google Cloud console and enable each API your application calls under APIs & Services > Library.
  3. Authenticate requests:

Example

Add googleapis and googleapis_auth to your package:

$ dart pub add googleapis googleapis_auth
import 'package:googleapis/drive/v3.dart';
import 'package:googleapis_auth/auth_io.dart';

Future<void> main() async {
  final httpClient = await clientViaApplicationDefaultCredentials(
    scopes: [DriveApi.driveMetadataReadonlyScope],
  );
  try {
    final drive = DriveApi(httpClient);
    final fileList = await drive.files.list(pageSize: 10);
    for (final file in fileList.files ?? const <File>[]) {
      print('${file.name} (${file.id})');
    }
  } finally {
    httpClient.close();
  }
}

Contributing

Refer to CONTRIBUTING.md for Contributor License Agreement (CLA) and pull request guidelines.

Workspace setup

This repository is configured as a Dart pub workspace. Resolve dependencies for all packages from the repository root:

$ dart pub get

Working on individual packages

When changing a standalone package such as googleapis_auth or discoveryapis_commons, run analysis, formatting checks, and tests inside that package directory:

$ cd googleapis_auth
$ dart analyze --fatal-infos
$ dart format --output=none --set-exit-if-changed .
$ dart test

When changing browser authentication flows in googleapis_auth, also run the Chrome test matrix:

$ dart test -p chrome --compiler dart2js,dart2wasm

If you modify discoveryapis_generator, also regenerate the test fixture package from the repository root and verify there are no unexpected diffs:

$ ./tool/verify_examples_setup.sh
$ git diff

Regenerating googleapis and googleapis_beta

  1. Fetch the latest discovery documents from the googleapis/discovery-artifact-manager submodule, apply patches from overrides/, and update config.yaml:

    $ ./tool/download.sh
    
  2. Review changes in config.yaml and discovery/ to decide whether a minor or major version bump is needed. Update version: in config.yaml and the corresponding changelog under resources/googleapis/CHANGELOG.md or resources/googleapis_beta/CHANGELOG.md.

  3. Regenerate generated/googleapis and generated/googleapis_beta and refresh workspace resolution:

    $ ./tool/local_rebuild.sh
    
  4. Validate configuration, analysis, and tests:

    $ (cd generator && dart analyze --fatal-infos && dart test)
    $ (cd generated/googleapis && dart analyze --fatal-infos && dart test)
    $ (cd generated/googleapis_beta && dart analyze --fatal-infos && dart test)
    

Discovery document overrides

To patch an upstream discovery document in discovery/ (for example, to work around an upstream schema bug in discovery/googleapis/places__v1.json), edit the <api>__<version>.json file under discovery/ and write the unified diff to overrides/:

$ git diff discovery/<package>/<api>__<version>.json > overrides/<name>.diff

When the override corresponds to a GitHub issue, name the diff after the issue number (for example, overrides/i123.diff). ./tool/download.sh automatically applies all overrides/*.diff patches with git apply.