Mercurial > lbo > hg > async-google-apis
view README.md @ 235:bfafde81aec3 default tip master
Link to example crates
author | Lewin Bormann <lbo@spheniscida.de> |
---|---|
date | Sun, 30 May 2021 16:19:15 +0200 |
parents | 2ec23776a200 |
children |
line wrap: on
line source
# `async-google-apis` This software generates asynchronous API stubs for Google APIs (and most likely any other API described by a Discovery document). It uses [`yup-oauth2`](https://github.com/dermesser/yup-oauth2) for the authorization logic. This project is still experimental. While for many complex APIs (Cloud Storage, Drive v3, Sheets v4) usable APIs including types and documentation are generated successfully, this doesn't mean that it will work on any other current or future Google API. ## What it looks like There are examples in this repository: * [`for Google Calendar`](https://github.com/dermesser/async-google-apis/blob/master/example_crates/calendar_example/src/main.rs) * [`for YouTube`](https://github.com/dermesser/async-google-apis/blob/master/example_crates/youtube_example/src/main.rs) * [`for Google Cloud Storage`](https://github.com/dermesser/async-google-apis/blob/master/example_crates/gcs_example/src/main.rs) * [`for Google Drive`](https://github.com/dermesser/async-google-apis/blob/master/example_crates/drive_example/src/main.rs) Also consider the documentation of these exemplary APIs: * [`calendar:v3`](https://borgac.net/~lbo/doc/target/doc/calendar_example/calendar_v3_types/) for Google Calendar. * [`drive:v3`](https://borgac.net/~lbo/doc/target/doc/drive_example/drive_v3_types/) for Google Drive. * [`storage:v1`](https://borgac.net/~lbo/doc/target/doc/gcs_example/storage_v1_types/) for Google Cloud Storage. * [`youtube:v3`](https://borgac.net/~lbo/doc/target/doc/youtube_example/youtube_v3_types/) for Youtube. ## Parts * `generate` contains a Python program fetching current Google Discovery documents (https://www.googleapis.com/discovery/v1/apis, see [documentation](https://developers.google.com/discovery/v1/reference)) and generating Rust code in the `generate/gen` directory. This is done very non-fancily using a few mustache templates and the `chevron` package. The script only takes two parameters, which you can discover using `--help`. In short, to generate an API stub for the API with ID `storage:v1` (Google Cloud Storage v1), run ```shell $ pipenv run ./generate.py --apis=storage:v1 ``` (install `pipenv` using `pip install --user pipenv` before, if you don't have it yet). See more details in that directory. * Consult `drive_example` or `gcs_example` for simple but useful examples of using the generated code. As you can see, it is reasonably easy! Use `cargo doc` to generate the documentation for generated code, as the API comments is translated into Rust doc comments. I try keeping them up-to-date as the API of the generated code occasionally changes. * `async-google-apis-common` contains shared code, for example the HTTP logic, used by the generated code, as well as some types (like errors) and as well as all imports. Include this crate in your dependencies when you are using the generated code in your project. * NOTE: some parts of the API -- for example: URL query parameters that are not represented as enums -- may require small manual adjustments to the generated code. If possible, this should be solved automatically, but sometimes it isn't yet. Refer to the example crates for more details. ## To Do * Integration tests: E.g. by writing a custom JSON service description and an accompanying server binary to run test code against.