Improved getting started experience

[DazWilkin]

Thanks for building this generator!

I struggled to understand how to use it.

After cloning the repo, I duly cargo run -- --help and was given 2 possible alternatives:

cargo run -- fetch-api-specs
cargo run -- generate

When I tried cargo run -- generate --help:

Generate libraries and command-line interface for said libraries based on Google API specifications.

The output will always be formatted using rustfmt. You can set the RUSTFMT environment variable to an empty value to
prevent formatting, which can safe some time during generation.

USAGE:
    mcp generate <spec-json-path> <output-directory>

FLAGS:
    -h, --help    
            Prints help information


ARGS:
    <spec-json-path>      
            The Google API specification as downloaded from the discovery service

    <output-directory>    
            The directory into which we will write all generated data

NOTE Is mcp equivalent to cargo run --? Or should I use mcp instead?

I looked for the <spec-json-path> in the repo but assume it isn't copy to rely on the live documents? I think, at this point, I should have just downloaded the Discovery document for Cloud Run (discovery) but, I was uncertain whether I should fetch-api-specs.

When I tried cargo run -- fetch-api-specs --help:

Fetch all API specs, in parallel, and generate their Rust code

USAGE:
    mcp fetch-api-specs <index-path> <spec-directory> <output-directory>

FLAGS:
    -h, --help    Prints help information

ARGS:
    <index-path>          Either the original Google index, or the mapped index we produced prior
    <spec-directory>      The directory into which we will write all downloaded specifications
    <output-directory>    The directory into which we will write the generated APIs

I'm unsure what the mapped index we produced prior refers to. I was hoping the original Google index could be the URL but the URL doesn't appear to be accepted:

cargo run -- fetch-api-specs https://www.googleapis.com/discovery/v1/apis ./specs ./output
error: No such file or directory (os error 2)

FR Permit use of URLs

After tweaking fetch-api-specs and downloading the URL to a file, the errors I received suggesting that this command does not recursively descend through the spec files that it references; I must manually download the specific service specs.

FR Couldn't the index recursively identify the service specs? For e.g. Cloud Run, it contains everything it needs:

{
  "kind": "discovery#directoryItem",
  "id": "run:v1",
  "name": "run",
  "version": "v1",
  ...
  "discoveryRestUrl": "https://run.googleapis.com/$discovery/rest?version=v1",
  ...
}

Finally, I realized fetch-api-specs is redundant for my needs.

But I still had to manually download the Cloud Run spec, again it would be nice to provide this as a URL

FR Reference discovery documents by URL or local file

Then I was happily able to generate the library that I need:

cargo run -- generate ./specs/run/v1/spec.json ./output/run/v1
2021-03-11 13:36:14,330 INFO  [google_rest_api_generator] api: creating source directory and Cargo.toml
2021-03-11 13:36:14,330 INFO  [google_rest_api_generator] api: building api desc
2021-03-11 13:36:14,418 INFO  [google_rest_api_generator] api: prepared APIDesc in 87.605238ms
2021-03-11 13:36:14,418 INFO  [google_rest_api_generator] api: writing lib './output/run/v1/lib/src/lib.rs'
2021-03-11 13:36:14,471 INFO  [google_rest_api_generator] getting all types
2021-03-11 13:36:14,746 INFO  [google_rest_api_generator] generating resources
2021-03-11 13:36:14,747 INFO  [google_rest_api_generator] creating resource actions
2021-03-11 13:36:14,749 INFO  [google_rest_api_generator] outputting
2021-03-11 13:36:15,143 INFO  [google_rest_api_generator] api: generated and formatted in 672.167212ms
2021-03-11 13:36:15,143 INFO  [google_rest_api_generator] api: done in 813.143264ms
2021-03-11 13:36:15,144 INFO  [google_cli_generator::cli] cli: building api desc
2021-03-11 13:36:15,223 INFO  [google_cli_generator::cli] cli: writing main './output/run/v1/cli/src/main.rs'
2021-03-11 13:36:15,284 INFO  [google_cli_generator::cli] cli: done in 139.596997ms

Thank you for reading this far! It's a very useful tool but it's not as approachable as it could be.

[mwilliammyers]

Hello! Sorry you had such a hard time getting started!

I have been wanting to make it easier to get a development environment and running for some time now. Although, we hope to publish all the crates sometime soon, so that might cover your use case. In the meantime, you can also specify our other repo
https://github.com/google-apis-rs/generated. It looks like you are looking for Cloud Run which is not available on master. You could try the WIP refactor/async branch as long as the caveats listed in #30 meet your needs.

Also, this project uses https://github.com/casey/just, you might find it easier to use that rather than running everything by hand.

[arn-the-long-beard]

Hi !

I also experience the same. It is a bit challenging to get started 😄 .

Let's try https://github.com/google-apis-rs/generated.git then !

[arn-the-long-beard]

Okay, I tried and I cannot use it on front end. I need to make it Wasm compatible.

[DazWilkin]

@mwilliammyers I apologize for not having responded to your reply.

Your guidance was helpful.

I continue to struggle using these repos.

I noticed in your [reply] on #24 that there's some syntax (with which I was unfamiliar) for referencing the generated packages which clearly is preferred and much simpler but not (!?) documented.

google_serviceusage = {
  git = "https://github.com/google-apis-rs/generated.git",
  package = "google-serviceusage1"
}